📚 课程目录第3章 Manifest文件基础

3. Manifest文件基础：Manifest文件定义、ManifestList与ManifestFile的关系、ManifestEntry结构

3.1 核心原理：Manifest 在 Iceberg 表体系中的定位

Apache Iceberg 采用“元数据层—清单层—数据文件层”的三级结构来管理海量数据文件。其中，Manifest 文件（清单文件）是连接元数据与数据文件的桥梁，它负责记录一张表某个快照（Snapshot）下所有数据文件的物理位置、分区信息、列统计与文件级元数据。理解 Manifest 的组织方式，是掌握 Iceberg 查询加速与增量读取的关键前提。

Manifest 文件本身是一个Avro 格式的文件，内部按行存储若干条 ManifestEntry。每个 ManifestEntry 对应一个数据文件（DataFile）或删除文件（DeleteFile），并携带该文件的状态标记（ADDED / EXISTING / DELETED）。Manifest 文件通常以 snap-xxx-1.avro 命名，存放在表的 metadata/ 目录下。

为了更直观地理解三层结构，下图展示了 Iceberg 表快照中 ManifestList、ManifestFile 与 ManifestEntry 之间的引用关系：

3.2 ManifestList 与 ManifestFile 的关系

ManifestList（清单列表）是 Iceberg 快照的入口文件，它本身也是一个 Avro 文件，通常以 snap-<snapshot-id>.avro 命名。ManifestList 中每一行描述一个 ManifestFile 的概要信息，包括：

manifest_path：Manifest 文件的存储路径
manifest_length：Manifest 文件字节长度
partition_spec_id：该 Manifest 使用的分区规范 ID
added_snapshot_id：添加该 Manifest 的快照 ID
added_data_files_count / existing_data_files_count / deleted_data_files_count：各类文件计数
partitions：分区摘要（含分区字段上下界）

ManifestList 与 ManifestFile 是一对多的引用关系：一个快照对应一个 ManifestList，而一个 ManifestList 可以引用多个 ManifestFile。每个 ManifestFile 负责管理一部分数据文件的元数据。这种设计使得 Iceberg 可以将不同分区或不同批次写入的数据文件分散到多个 Manifest 中，从而支持并发写入与增量提交。

在查询时，Iceberg 引擎首先读取 ManifestList，获取所有 ManifestFile 的路径与统计信息；然后根据查询条件（如分区过滤）只读取必要的 ManifestFile，避免扫描全部清单。这种两级过滤机制是 Iceberg 查询加速的重要基础。

3.3 ManifestEntry 结构详解

ManifestEntry 是 Manifest 文件中的最小数据单元，每条记录对应一个数据文件或删除文件。其核心字段如下：

字段名	类型	说明
`status`	int	0=EXISTING，1=ADDED，2=DELETED
`snapshot_id`	long	该条目所属的快照 ID（可选，默认继承 Manifest 的 added_snapshot_id）
`data_file`	struct	包含文件路径、分区、格式、列统计等嵌套字段
`file_sequence_number`	long	文件写入时的全局递增序号，用于并发控制与时间旅行

其中 data_file 结构体又包含以下关键子字段：

file_path：数据文件在存储中的完整路径
file_format：PARQUET / ORC / AVRO
partition：分区字段的值（如 dt=2024-01-01）
record_count：文件中的记录总数
file_size_in_bytes：文件字节大小
column_sizes：各列压缩后的大小映射
value_counts：各列非空值数量
lower_bounds / upper_bounds：各列的最小/最大值（用于谓词下推）

3.4 案例：一次数据写入如何生成 Manifest

假设我们向 Iceberg 表 orders 插入一批新数据，分区字段为 order_date。写入流程如下：

Spark / Flink 写入任务生成若干 Parquet 数据文件，存放在数据目录中。
Iceberg 为这批写入创建一个新的 Manifest 文件，其中每条 ManifestEntry 的 status 标记为 ADDED（1），并填充数据文件的路径、分区、统计信息。
同时，对于之前已存在但未被修改的 Manifest 文件，Iceberg 会将其中的条目标记为 EXISTING（0），并复制到新的 Manifest 中（或直接复用原 Manifest）。
如果某些旧数据文件被删除（如执行了 DELETE 操作），则对应条目标记为 DELETED（2）。
最后，Iceberg 生成一个新的 ManifestList 文件，引用上述所有 ManifestFile，并更新元数据文件 v2.metadata.json 中的当前快照指针。

以下是一个简化的 ManifestEntry 示例（JSON 形式便于阅读）：

{
  "status": 1,
  "snapshot_id": 918271563,
  "data_file": {
    "file_path": "s3://bucket/warehouse/orders/order_date=2024-06-01/0000.parquet",
    "file_format": "PARQUET",
    "partition": {"order_date": "2024-06-01"},
    "record_count": 12000,
    "file_size_in_bytes": 268435456,
    "column_sizes": {"order_id": 1024, "customer_id": 2048},
    "value_counts": {"order_id": 12000, "customer_id": 11998},
    "lower_bounds": {"order_id": 100001, "customer_id": 5001},
    "upper_bounds": {"order_id": 112000, "customer_id": 6200}
  },
  "file_sequence_number": 34
}

3.5 常见误区与调优建议

误区 1：认为 Manifest 文件越多越好。实际上，过多的 Manifest 文件会导致查询时需要读取大量清单文件，增加元数据开销。建议通过 rewrite_manifests 或 rewrite_data_files 定期合并小 Manifest。

误区 2：忽略 Manifest 中的列统计信息。如果写入时未正确生成 lower_bounds 和 upper_bounds，查询引擎将无法进行文件级裁剪，导致扫描所有数据文件。确保写入端开启统计信息收集（默认开启）。

调优建议：对于分区表，尽量让每个分区只对应少量 Manifest 文件；对于频繁更新的表，可设置 write.manifest.target-size-bytes（默认 8MB）来控制 Manifest 文件大小，避免产生过多小文件。

理解 Manifest 的三层结构，是后续掌握 Iceberg 查询加速（如元数据过滤、分区裁剪、Z-Order 排序）的基础。在实际生产环境中，通过监控 Manifest 文件数量与大小，可以快速定位元数据膨胀问题，从而优化表性能。