【Iceberg表规范】Manifests(manifest files)、Snapshots和Table Metadata
目录
- 1. Manifests(manifest files)
- 2. Snapshots
-
- 2.1 Manifest List
- 2.2 Scan Planning
- 2.3 Snapshot Reference快照引用
- 3. Table Metadata
1. Manifests(manifest files)
manifest file也是一个data file，使用Iceberg的表format、schemas、column projection列投影
一个manifest file要么指向data files，要么指向delete files。在数据Scanning时，会先读取delete files
avro格式的manifest file包含如下key:value数据：
| v1 | v2 | Key | Value |
|---|---|---|---|
| required | required | schema | manifest file的json格式schema |
| optional | required | schema-id | 字符串形式的schema ID |
| required | required | partition-spec | json格式的表分区字段 |
| optional | required | partition-spec-id | 字符串形式的partition-spec ID |
| optional | required | format-version | 字符串形式的表格式版本号 |
| 空白 | required | content | 数据文件的内容形式: data或deletes |
上面的schema各字段说明如下：
| v1 | v2 | 字段ID，字段名称 | 数据类型 | 描述 |
|---|---|---|---|---|
| required | required | 0 status | int，含义: 0: EXISTING 1: ADDED 2: DELETED | 用于追踪是data file还是delete file |
| required | optional | 1 snapshot_id | long | data file或delete file所属的snapshot id |
| 空白 | optional | 3 sequence_number | long | 当是data file时，所对应的Sequence number |
| required | required | 2 data_file | data_file struct |
data_file struct各字段说明如下：
| v1 | v2 | Field id, name | Type | Description |
|---|---|---|---|---|
| 空白 | required | 134 content | int，含义: 0: DATA, 1: POSITION DELETES, 2: EQUALITY DELETES | 数据文件的内容类型：0：data file，1：position类型的delete file，2：值等式类型的delete file |
| required | required | 100 file_path | string | 数据文件的Path(带文件系统schema) |
| required | required | 101 file_format | string | 数据文件的格式：avro、orc、parquet |
| required | required | 102 partition | struct<…> | Partition data tuple |
| required | required | 103 record_count | long | 数据文件中数据的行数 |
| required | required | 104 file_size_in_bytes | long | 数据文件的大小 |
| required | 空白 | 105 block_size_in_bytes | long | Deprecated. Always write a default in v1. Do not write in v2. |
| optional | 空白 | 106 file_ordinal | int | Deprecated. Do not write. |
| optional | 空白 | 107 sort_columns | list<112: int> | Deprecated. Do not write. |
| optional | optional | 108 column_sizes | map<117: int, 118: long> | key为字段唯一ID，value为字段数据占磁盘的大小。对于avro行式数据格式，column_sizes等于null |
| optional | optional | 109 value_counts | map<119: int, 120: long> | key为字段唯一ID，value为字段数据中值的数量(包含null和NaN) |
| optional | optional | 110 null_value_counts | map<121: int, 122: long> | key为字段唯一ID，value为字段数据中null值的数量 |
| optional | optional | 137 nan_value_counts | map<138: int, 139: long> | 为字段唯一ID，value为字段数据中NaN值的数量 |
| optional | optional | 111 distinct_counts | map<123: int, 124: long> | key为字段唯一ID，value为字段数据去重后的值数量 |
| optional | optional | 125 lower_bounds | map<126: int, 127: binary> | key为字段唯一ID，value为字段数据的最小值，最小值被序列化为二进制，序列化方式参考： |
| optional | optional | 128 upper_bounds | map<129: int, 130: binary> | key为字段唯一ID，value为字段数据的最大值，最大值被序列化为二进制，序列化方式参考： |
| optional | optional | 131 key_metadata | binary | Implementation-specific key metadata for encryption |
| optional | optional | 132 split_offsets | list<133: long> | data file的Split offsets |
| 空白 | optional | 135 equality_ids | list<136: int> | 值等式形式的delete file中，用于进行值等式计算的多个字段ID |
| optional | optional | 140 sort_order_id | int | Sort order ID |
- sort_order_id：只有data file和值等式形式的delete file需要，position delete file不需要sort order id
2. Snapshots
元数据信息位于vN.metadata.json中
| v1 | v2 | 字段名称 | 描述 |
|---|---|---|---|
| required | required | snapshot-id | long类型的唯一ID |
| optional | optional | parent-snapshot-id | 该snapshot的上一个snapshot id |
| 空白 | required | sequence-number | A monotonically increasing long that tracks the order of changes to a table |
| required | required | timestamp-ms | snapshot创建的时间 |
| optional | required | manifest-list | 该snapshot对应的manifest list的Path |
| optional | 空白 | manifests | 该snapshot对应的多个manifest file的Path列表 |
| optional | required | summary | A string map that summarizes the snapshot changes, including operation |
| optional | optional | schema-id | snapshot创建时的schema ID |
summary的operation字段可取的值有：
- append：只添加data files
- replace：添加data files和delete files，但表数据并为改变。比如compaction操作
- overwrite：添加data files和delete files，但表数据改变。比如overwrite操作
- delete：添加delete files
2.1 Manifest List
manifest list也是一个data file，使用Iceberg的表format、schemas、column projection列投影。manifest list各字段含义如下：
| v1 | v2 | Field id, name | Type | Description |
|---|---|---|---|---|
| required | required | 500 manifest_path | string | manifest file的Path |
| required | required | 501 manifest_length | long | manifest file的长度 |
| required | required | 502 partition_spec_id | int | partition spec ID |
| 空白 | required | 517 content | int，含义: 0: data, 1: deletes | manifest file对应的文件类型，date files或delete files |
| 空白 | required | 515 sequence_number | long | manifest file对应的sequence number |
| 空白 | required | 516 min_sequence_number | long | manifest file对应的data files或delete files的最小sequence number |
| required | required | 503 added_snapshot_id | long | manifest file对应的snapshot id |
| optional | required | 504 added_files_count | int | manifest file对应的data file数量 |
| optional | required | 505 existing_files_count | int | manifest file对应的data file数量 + delete file数量 |
| optional | required | 506 deleted_files_count | int | manifest file对应的delete file数量 |
| optional | required | 512 added_rows_count | long | manifest file对应的所有data file的数据量 |
| optional | required | 513 existing_rows_count | long | manifest file对应的所有data file的数据量 + 所有delete file的数据量 |
| optional | required | 514 deleted_rows_count | long | manifest file对应的所有delete file的数据量 |
| optional | optional | 507 partitions | list<508: field_summary> | manifest file对应的多个分区字段的汇总信息列表 |
| optional | optional | 519 key_metadata | binary | Implementation-specific key metadata for encryption |
field_summary的数据类型为struct，各字段信息如下：
| v1 | v2 | Field id, name | Type | Description |
|---|---|---|---|---|
| required | required | 509 contains_null | boolean | manifest file对应的一个分区字段是否有一个null分区 |
| optional | optional | 518 contains_nan | boolean | manifest file对应的一个分区字段是否有一个NaN分区 |
| optional | optional | 510 lower_bound | bytes [1] | manifest file对应的一个分区字段的分区最小值(不含null和NaN)，最小值被序列化为二进制，序列化方式参考： |
| optional | optional | 511 upper_bound | bytes [1] | manifest file对应的一个分区字段的分区最大值(不含null和NaN)，最大值被序列化为二进制，序列化方式参考： |
2.2 Scan Planning
当读取data files的时候，同时满足下面条件的delete files也会被读取
对于position delete files:
- delete file的分区字段和分区值，和data file的一样
- delete file的sequence number小于等于data file的sequence number
对于等式值delete files:
3. delete file的分区字段和分区值，和data file的一样
4. delete file的sequence number小于data file的sequence number
2.3 Snapshot Reference快照引用
Iceberg的表有多个Snapshot，每个Snapshot都有一个tag作为label，而Branches可以看作是一个可变的Snapshot列表，main branch指向最新的Snapshot，而老的branch会因为Snapshot expire而被删除。下面是Snapshot Reference各字段的信息：
| v1 | v2 | 字段名称 | 数据类型 | 描述 |
|---|---|---|---|---|
| required | required | snapshot-id | long | 一个reference的snapshot id |
| required | required | type | string | reference的类型, 可选的参数为：tag、branch |
| optional | optional | min-snapshots-to-keep | int | 只用于branch类型。当所有snapshot都过期时，默认最小保留多少个snapshot不过期。默认为表属性history.expire.min-snapshots-to-keep |
| optional | optional | max-snapshot-age-ms | long | 只用于branch类型。最大的snapshot过期时间。默认为表属性history.expire.max-snapshot-age-ms |
| optional | optional | max-ref-age-ms | long | 对于snapshot references(除了main branch，main branch永远不会过期)，默认最大snapshot references过期时间。默认为表属性history.expire.max-ref-age-ms |
有效的snapshot reference储存在table metadata的refs map中。序列化请参考：
3. Table Metadata
Table metadata是一种json格式的数据，其实就是vN.metadata.json文件。各字段信息如下，序列化请参考：
| v1 | v2 | 字段名称 | 描述 |
|---|---|---|---|
| required | required | format-version | 表规范的版本号，可选的值为1、2 |
| optional | required | table-uuid | 表创建时生成的UUID |
| required | required | location | 表数据储存的HDFS根path，如hdfs://nnha/user/iceberg/warehouse/test_db/test_tb |
| 空白 | required | last-sequence-number | 表的snapshot的最新sequence number |
| required | required | last-updated-ms | 表最后一次更新的时间 |
| required | required | last-column-id | 表的最大column id，确保以后指定的column id不重复 |
| required | 空白 | schema | 表当前的schema，在版本2被Deprecated，使用schemas和current-schema-id替换 |
| optional | required | schemas | schema列表，每个元素都包含schema-id |
| optional | required | current-schema-id | 表当前schema的id |
| required | 空白 | partition-spec | 表当前的partition spec，只储存fields。只是用于writer进行数据分区。已经被Deprecated，使用partition-specs和default-spec-id进行替换 |
| optional | required | partition-specs | partition spec列表 |
| optional | required | default-spec-id | write默认使用的当前partition spec id |
| optional | required | last-partition-id | 最大的分区字段id，确保以后指定的partition字段id不重复 |
| optional | optional | properties | 储存定义的表属性 |
| optional | optional | current-snapshot-id | 表当前snapshot id |
| optional | optional | snapshots | 一个有效的snapshot列表 |
| optional | optional | snapshot-log | 一个列表，每个元素是包含两个key(timestamp和snapshot id)的map。列表中的元素有新的commit时在新的vN.metadata.json会新增，snpashot过期在新的vN.metadata.json则会删除 |
| optional | optional | metadata-log | 一个列表，每个元素是包含两个key(timestamp和历史vN.metadata.json文件的path)的map |
| optional | required | sort-orders | sort order列表 |
| optional | required | default-sort-order-id | 表默认sort order id. 用于write进行写数据排序 |
| 空白 | optional | refs | 一个列表，每个元素的key是表的snapshot reference唯一名称，value是snapshot reference objects |