【Iceberg表规范】Manifests(manifest files)、Snapshots和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数据：

v1v2KeyValuerequiredrequiredschemamanifest file的json格式schemaoptionalrequiredschema-id字符串形式的schema IDrequiredrequiredpartition-specjson格式的表分区字段optionalrequiredpartition-spec-id字符串形式的partition-spec IDoptionalrequiredformat-version字符串形式的表格式版本号空白requiredcontent数据文件的内容形式: data或deletes

上面的schema各字段说明如下：

v1v2字段ID，字段名称数据类型描述requiredrequired0 statusint，含义: 0: EXISTING 1: ADDED 2: DELETED用于追踪是data file还是delete filerequiredoptional1 snapshot_idlongdata file或delete file所属的snapshot id空白optional3 sequence_numberlong当是data file时，所对应的Sequence numberrequiredrequired2 data_filedata_file struct

data_file struct各字段说明如下：

v1v2Field id, nameTypeDescription空白required134 contentint，含义: 0: DATA, 1: POSITION DELETES, 2: EQUALITY DELETES数据文件的内容类型：0：data file，1：position类型的delete file，2：值等式类型的delete filerequiredrequired100 file_pathstring数据文件的Path(带文件系统schema)requiredrequired101 file_formatstring数据文件的格式：avro、orc、parquetrequiredrequired102 partitionstructPartition data tuplerequiredrequired103 record_countlong数据文件中数据的行数requiredrequired104 file_size_in_byteslong数据文件的大小required空白105 block_size_in_byteslongDeprecated. Always write a default in v1. Do not write in v2.optional空白106 file_ordinalintDeprecated. Do not write.optional空白107 sort_columnslistDeprecated. Do not write.optionaloptional108 column_sizesmapkey为字段唯一ID，value为字段数据占磁盘的大小。对于avro行式数据格式，column_sizes等于nulloptionaloptional109 value_countsmapkey为字段唯一ID，value为字段数据中值的数量(包含null和NaN)optionaloptional110 null_value_countsmapkey为字段唯一ID，value为字段数据中null值的数量optionaloptional137 nan_value_countsmap为字段唯一ID，value为字段数据中NaN值的数量optionaloptional111 distinct_countsmapkey为字段唯一ID，value为字段数据去重后的值数量optionaloptional125 lower_boundsmapkey为字段唯一ID，value为字段数据的最小值，最小值被序列化为二进制，序列化方式参考：optionaloptional128 upper_boundsmapkey为字段唯一ID，value为字段数据的最大值，最大值被序列化为二进制，序列化方式参考：optionaloptional131 key_metadatabinaryImplementation-specific key metadata for encryptionoptionaloptional132 split_offsetslistdata file的Split offsets空白optional135 equality_idslist值等式形式的delete file中，用于进行值等式计算的多个字段IDoptionaloptional140 sort_order_idintSort order ID

• sort_order_id：只有data file和值等式形式的delete file需要，position delete file不需要sort order id

2. Snapshots

元数据信息位于vN.metadata.json中

v1v2字段名称描述requiredrequiredsnapshot-idlong类型的唯一IDoptionaloptionalparent-snapshot-id该snapshot的上一个snapshot id空白requiredsequence-numberA monotonically increasing long that tracks the order of changes to a tablerequiredrequiredtimestamp-mssnapshot创建的时间optionalrequiredmanifest-list该snapshot对应的manifest list的Pathoptional空白manifests该snapshot对应的多个manifest file的Path列表optionalrequiredsummaryA string map that summarizes the snapshot changes, including operationoptionaloptionalschema-idsnapshot创建时的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各字段含义如下：

v1v2Field id, nameTypeDescriptionrequiredrequired500 manifest_pathstringmanifest file的Pathrequiredrequired501 manifest_lengthlongmanifest file的长度requiredrequired502 partition_spec_idintpartition spec ID空白required517 contentint，含义: 0: data, 1: deletesmanifest file对应的文件类型，date files或delete files空白required515 sequence_numberlongmanifest file对应的sequence number空白required516 min_sequence_numberlongmanifest file对应的data files或delete files的最小sequence numberrequiredrequired503 added_snapshot_idlongmanifest file对应的snapshot idoptionalrequired504 added_files_countintmanifest file对应的data file数量optionalrequired505 existing_files_countintmanifest file对应的data file数量 + delete file数量optionalrequired506 deleted_files_countintmanifest file对应的delete file数量optionalrequired512 added_rows_countlongmanifest file对应的所有data file的数据量optionalrequired513 existing_rows_countlongmanifest file对应的所有data file的数据量 + 所有delete file的数据量optionalrequired514 deleted_rows_countlongmanifest file对应的所有delete file的数据量optionaloptional507 partitionslistmanifest file对应的多个分区字段的汇总信息列表optionaloptional519 key_metadatabinaryImplementation-specific key metadata for encryption

field_summary的数据类型为struct，各字段信息如下：

v1v2Field id, nameTypeDescriptionrequiredrequired509 contains_nullbooleanmanifest file对应的一个分区字段是否有一个null分区optionaloptional518 contains_nanbooleanmanifest file对应的一个分区字段是否有一个NaN分区optionaloptional510 lower_boundbytes [1]manifest file对应的一个分区字段的分区最小值(不含null和NaN)，最小值被序列化为二进制，序列化方式参考：optionaloptional511 upper_boundbytes [1]manifest file对应的一个分区字段的分区最大值(不含null和NaN)，最大值被序列化为二进制，序列化方式参考： 2.2 Scan Planning

当读取data files的时候，同时满足下面条件的delete files也会被读取

对于position delete files:

1. delete file的分区字段和分区值，和data file的一样
2. 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各字段的信息：

v1v2字段名称数据类型描述requiredrequiredsnapshot-idlong一个reference的snapshot idrequiredrequiredtypestringreference的类型, 可选的参数为：tag、branchoptionaloptionalmin-snapshots-to-keepint只用于branch类型。当所有snapshot都过期时，默认最小保留多少个snapshot不过期。默认为表属性history.expire.min-snapshots-to-keepoptionaloptionalmax-snapshot-age-mslong只用于branch类型。最大的snapshot过期时间。默认为表属性history.expire.max-snapshot-age-msoptionaloptionalmax-ref-age-mslong对于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文件。各字段信息如下，序列化请参考：部分

v1v2字段名称描述requiredrequiredformat-version表规范的版本号，可选的值为1、2optionalrequiredtable-uuid表创建时生成的UUIDrequiredrequiredlocation表数据储存的HDFS根path，如hdfs://nnha/user/iceberg/warehouse/test_db/test_tb空白requiredlast-sequence-number表的snapshot的最新sequence numberrequiredrequiredlast-updated-ms表最后一次更新的时间requiredrequiredlast-column-id表的最大column id，确保以后指定的column id不重复required空白schema表当前的schema，在版本2被Deprecated，使用schemas和current-schema-id替换optionalrequiredschemasschema列表，每个元素都包含schema-idoptionalrequiredcurrent-schema-id表当前schema的idrequired空白partition-spec表当前的partition spec，只储存fields。只是用于writer进行数据分区。已经被Deprecated，使用partition-specs和default-spec-id进行替换optionalrequiredpartition-specspartition spec列表optionalrequireddefault-spec-idwrite默认使用的当前partition spec idoptionalrequiredlast-partition-id最大的分区字段id，确保以后指定的partition字段id不重复optionaloptionalproperties储存定义的表属性optionaloptionalcurrent-snapshot-id表当前snapshot idoptionaloptionalsnapshots一个有效的snapshot列表optionaloptionalsnapshot-log一个列表，每个元素是包含两个key(timestamp和snapshot id)的map。列表中的元素有新的commit时在新的vN.metadata.json会新增，snpashot过期在新的vN.metadata.json则会删除optionaloptionalmetadata-log一个列表，每个元素是包含两个key(timestamp和历史vN.metadata.json文件的path)的mapoptionalrequiredsort-orderssort order列表optionalrequireddefault-sort-order-id表默认sort order id. 用于write进行写数据排序空白optionalrefs一个列表，每个元素的key是表的snapshot reference唯一名称，value是snapshot reference objects