📚 课程目录第4章元数据文件详解

4、元数据文件详解：Metadata文件、Manifest List、Manifest文件的格式与作用

4.1 三类元数据文件的层级关系

Iceberg 表的所有变更都通过元数据文件进行追踪。理解元数据文件，是掌握 Iceberg 快照隔离与时间旅行特性的基础。整个元数据体系呈现严格的树形层级：Metadata 文件位于最顶层，描述表当前状态；它通过指针指向一个或多个Manifest List 文件（也称快照清单）；每个 Manifest List 又进一步指向若干Manifest 文件；而 Manifest 文件才是真正记录数据文件（Data Files）与删除文件（Delete Files）明细的载体。

这种分层设计带来了两个关键优势：写入并发友好（不同分区可独立写入不同 Manifest）与快速元数据过滤（查询时先读 Manifest List 中的统计信息，跳过无关 Manifest）。

4.2 Metadata 文件：表的“版本指针”

Metadata 文件是 Iceberg 表的当前状态快照，以 JSON 格式存储。每次对表执行提交操作（写入、删除、改 Schema、分区演进等），都会生成一个新的 Metadata 文件，文件名形如 00001-xxxx.metadata.json。表目录下的 version-hint.text 文件记录当前最新版本号，供引擎快速定位。

Metadata 文件的核心字段包括：

format-version：元数据格式版本，目前为 1 或 2（v2 支持删除文件与行级更新）。
table-uuid：表的全局唯一标识，用于防止错误指向其他表的元数据。
location：表数据存储的根目录。
last-sequence-number：全局单调递增的序号，用于 v2 格式的冲突检测。
current-snapshot-id：当前快照 ID，指向 Manifest List。
snapshots：历史快照列表（含每个快照的 timestamp、manifest-list 路径）。
schema：当前表结构（含字段 ID、名称、类型）。
partition-spec：分区定义（如按日期字段 day 转换）。
sort-orders：表的排序顺序定义。

一个简化的 Metadata 文件内容示例如下：

{
  "format-version": 2,
  "table-uuid": "9c12d4e2-...",
  "location": "s3://warehouse/db/events",
  "last-sequence-number": 34,
  "current-snapshot-id": 882145678,
  "snapshots": [
    {"snapshot-id": 882145678, "timestamp-ms": 1710000000000,
     "manifest-list": "s3://.../snap-882145678.avro"}
  ],
  "schema": {"type": "struct", "fields": [
    {"id": 1, "name": "event_id", "type": "long"},
    {"id": 2, "name": "event_time", "type": "timestamp"},
    {"id": 3, "name": "category", "type": "string"}
  ]},
  "partition-spec": [{"source-id": 2, "transform": "day", "name": "event_day"}]
}

关键认知：Metadata 文件本身不包含数据文件列表，只包含“指针”。因此它非常轻量（通常几十 KB），即使表有数万个数据文件，Metadata 文件也不会膨胀。

4.3 Manifest List：快照的“目录页”

每个快照对应一个 Manifest List 文件（Avro 格式），它列出了该快照引用的所有 Manifest 文件。Manifest List 中每条记录包含：

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：分区摘要（每个分区的 lower_bound / upper_bound 等统计）。

Manifest List 的核心作用是查询裁剪。当执行查询时，引擎先读取 Manifest List，根据分区统计信息判断哪些 Manifest 可能包含匹配数据，从而跳过完全无关的 Manifest 文件。例如，查询 WHERE event_day = '2024-03-10' 时，如果某个 Manifest 的分区范围是 2024-03-01 至 2024-03-05，则直接跳过。

4.4 Manifest 文件：数据文件的“明细账”

Manifest 文件（Avro 格式）是元数据体系的最底层，直接记录每一个数据文件或删除文件的详细条目。每个 Manifest 通常对应一个分区或一组写入操作产生的文件。Manifest 条目包含以下关键字段：

字段	说明	示例值
file_path	数据文件完整路径	s3://.../event_day=2024-03-10/0001.parquet
file_format	文件格式	PARQUET / ORC / AVRO
partition	该文件所属分区值	{event_day: 2024-03-10}
record_count	文件内记录数	1_250_000
file_size_in_bytes	文件字节大小	268_435_456
column_sizes / value_counts	列级大小与计数统计	{"1": 1024, "2": 2048}
lower_bounds / upper_bounds	各列的最小/最大值（用于谓词下推）	{"2": 2024-03-10T00:00}
key_metadata	加密密钥元数据（可选）	null
split_offsets	可切分偏移量（用于并行读取）	[4, 1048576]

在 v2 格式中，Manifest 还区分 data-file 条目与 delete-file 条目。删除文件又分为位置删除（position delete）与等值删除（equality delete），分别用于处理不同场景下的行级更新。

4.5 案例：一次 INSERT 操作产生的元数据变化

假设对 events 表执行一次 INSERT 写入 100 个新文件，Iceberg 的提交过程如下：

引擎将新数据文件写入数据目录（如 event_day=2024-03-10/ 下）。
为这些新文件创建 1 个或多个新的 Manifest 文件（按分区或文件数量拆分）。
创建新的 Manifest List，包含旧 Manifest 中未变的部分（复用）以及新增的 Manifest。
生成新的 Metadata 文件（版本号 +1），将 current-snapshot-id 指向新的 Manifest List。
原子性地将 version-hint.text 更新为新版本号。

整个过程不重写任何旧数据文件，也不修改旧 Manifest。旧快照仍然可以通过历史 Metadata 文件访问，这就是 Iceberg 时间旅行的实现基础。

4.6 常见误区与调优建议

误区一：认为 Manifest 文件越多越好。虽然 Manifest 拆分有助于写入并发，但过多的小 Manifest 会导致查询时元数据读取开销增大。建议通过 write.manifest.target-size-bytes（默认约 8MB）控制 Manifest 大小，并定期执行 REWRITE MANIFESTS 合并小 Manifest。

误区二：忽略 Manifest List 的统计信息。如果分区字段选择不当（如高基数字段直接分区），会导致 Manifest List 中分区统计失效，查询无法裁剪。应优先使用低基数字段或使用转换（如 hours(ts)、bucket(id, 16)）来保证裁剪效率。

  调优建议：对于频繁更新的表，可设置 write.metadata.previous-versions-max 控制保留的历史 Metadata 文件数量，避免元数据目录无限膨胀。同时，使用 write.metadata.metrics.default 配置列统计信息的收集粒度，在存储开销与查询性能之间取得平衡。

理解这三类文件的职责边界，是后续学习 Iceberg 表维护（如过期快照清理、孤儿文件删除）和性能调优的前提。在实际生产环境中，通过 org.apache.iceberg.util.JsonUtil 或 Spark 的 IcebergTable API 可以读取这些文件进行诊断，但日常运维中更推荐使用 ALTER TABLE ... SET TBLPROPERTIES 或 CALL 存储过程来管理元数据生命周期。