【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数据：

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为字段数据的最小值，最小值被序列化为二进制，序列化方式参考：<Single-value serialization>
optional	optional	128 upper_bounds	map<129: int, 130: binary>	key为字段唯一ID，value为字段数据的最大值，最大值被序列化为二进制，序列化方式参考：<Single-value serialization>
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)，最小值被序列化为二进制，序列化方式参考：<Single-value serialization>
optional	optional	511 upper_bound	bytes [1]	manifest file对应的一个分区字段的分区最大值(不含null和NaN)，最大值被序列化为二进制，序列化方式参考：<Single-value serialization>

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各字段的信息：

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中。序列化请参考：<JSON serialization>部分

3. Table Metadata

Table metadata是一种json格式的数据，其实就是vN.metadata.json文件。各字段信息如下，序列化请参考：<JSON serialization>部分

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