浅谈iceberg的存储文件

这是我的第100篇原创文章

【前言】

上一篇文章介绍了如何通过java api对iceberg进行操作。这次我们来聊聊iceberg里的存储文件。

iceberg中的持久化存储的文件可以简单的分为数据文件和元数据文件。数据文件就是存储数据记录的文件，而元数据文件又可以分为元数据描述文件、清单列表文件（manifest list），或者根据文件名又可以称为快照文件、以及清单文件（manifest file）。三类文件通过层级关系相互关联起来。下面就分别详细介绍下文件的具体内容与格式。

【数据文件】

通常在表存储目录的data子目录下，存放的是实际数据记录的文件，文件的格式在建表时指定，默认为parquet。当然也可以指定为orc、textfile等支持的类型。

另外，在有定义分区字段的表中，数据写入时会按照分区字段的值依次创建子目录，最终的数据文件则存放在这些子目录中。

注：对于api的操作，可以自定义数据的存储路径。

【元数据文件】

该目录主要存放记录表的元数据信息的文件，可以分为如下几类：

1. $VersionID-$UUID$Extension

该文件记录表的元数据信息。在创建表的时候，会同步创建该文件，此后的每次操作都会产生新的元数据文件。

文件名中的 $VersionID为版本号，共5位长度；$UUID是通过UUID库生成的随机32位的ID，$Extension为文件的后缀，默认情况下为".metadata.json"，如果对元数据指定了压缩方式，那么会在".metadata.json"的前面加上压缩类型的名称，例如"gzip.metadata.json"。

如文件名中的后缀描述一样，该文件采用json格式进行存储，下面罗列了各字段的含义：

• format-version

  
  

• 元数据文件格式的版本，默认为1，代表为v1版本。

• table-uuid

• 表的uuid。

• location

• 元数据文件存储位置URI，通常是在hdfs中的全路径。
  

• last-updated-ms

• 元数据最后更新时间

• last-column-id

• 最后一个列字段的ID

• schema

• 表格式定义说明，属于v1版本中的必需字段，在v2版本中以下面两个字段替代。

• current-schema-id

• 当前表格式定义（schemas中包含的schema数组）使用的schema id。

• schemas

• v2格式中表格式定义说明，字段的值为一个数组，记录了历史schema的变更情况，数组中的每一项均为表schema的对象，包括类型、ID、字段数据，配合上面的current-schema-id就能知道当前版本的表格式定义是怎样的了。

  
  

  "schemas" : [ {
      "type" : "struct",
      "schema-id" : 0,
      "fields" : [ {
        "id" : 1,
        "name" : "id",
        "required" : false,
        "type" : "int"
      }, {
        "id" : 2,
        "name" : "name",
        "required" : false,
        "type" : "string"
      }, {
        "id" : 3,
        "name" : "birth",
        "required" : false,
        "type" : "string"
      } ]
    } ]

• partition-spec

• 表的分区字段定义说明，同样属于v1版本中的必需字段

• default-spec-id

• 默认使用的分区的ID

• partition-specs

• 表的分区字段定义说明，v2格式中的必须字段。字段的值为一个数组，记录了历史的分区定义，数组中的每一项均为一个分区对象，其中包括ID和分区字段说明，对于分区字段说明则又包含如下几个字段。

  • name

    
    

  • 分区字段的名称。

  • transform

  • 分区字段的转换方式，一般来说是字段本身，即"identity"； 但可以是year、month、day、bucket等转换函数，实现不同的分区的逻辑，这里的值就是对应转换函数名。

  • source-id

  • 对应schema中的filed字段的ID

  • field-id

  • 分区字段定义的ID，默认从1000开始递增。

  与schemas类似，配合default-spec-id字段可以知道当前的分区定义。

• last-partition-id

• 最后一个分区字段的ID，即对应partition-specs中分区字段的filed-id。

• default-sort-order-id

• 默认排序的ID

• sort-orders

• 字段排序定义，默认为空数组

• properties

• 表的属性定义。

• current-snapshot-id

• 当前使用的快照ID

• snapshots

• 快照文件列表，具体值为一个数组，数组中的每一项均为一个快照信息，每个快照信息又是一个对象，包括ID（snapshot-id）、父snapshot的ID（parent-snapshot-id）、生成的时间戳（timestamp-ms）、概要信息（summary），文件清单（manifest-list或manifests）、表schema的ID（schema_id），其中概要信息包括的常见的子字段有：

  • operation

    
    

  • 本次快照引发的操作，例如append、delete、replace、overwrite。

  • added-data-files

  • 本次快照添加的文件数，operation操作为append才有该字段

  • added-records

  • 本次快照添加的记录数，operation操作为append才有该字段

  • added-files-size

  • 本次快照添加的文件大小，operation操作为append才有该字段

  • deleted-data-files

  • 本次触发快照的操作所删除的文件数，operation操作为delete才有该字段

  • delete-records

  • 本次触发快照的操作所删除的记录数，operation操作为delete才有该字段

  • removed-files-size

  • 本次触发快照的操作所删除的文件大小，operation操作为delete才有该字段

  • changed-partition-count

  • 本次涉及变更的分区数

  • total-records

  • 本次快照完成后，表中总的记录数

  • total-files-size

  • 本次快照完成后，总的文件大小

  • total-data-files

  • 本次快照完成后，总的文件数

  • total-delete-files

  • 本次快照完成后，总的删除文件数

  
  

  一个实际实例如下所示

  "snapshots" : [ {
    "snapshot-id" : 8319024382941793184,
    "timestamp-ms" : 1678669777251,
    "summary" : {
      "operation" : "append",
      "added-data-files" : "2",
      "added-records" : "4",
      "added-files-size" : "1978",
      "changed-partition-count" : "2",
      "total-records" : "4",
      "total-files-size" : "1978",
      "total-data-files" : "2",
      "total-delete-files" : "0",
      "total-position-deletes" : "0",
      "total-equality-deletes" : "0"
    },
    "manifest-list" : "hdfs://hdfsHACluster/user/hive/warehouse/iceberg_db.db/developer/metadata/snap-8319024382941793184-1-051dc090-a770-441c-b76b-b97a591a97c7.avro",
    "schema-id" : 0
  } ]

• snapshot-log

• snapshot的历史集合，以数组形式表示。

• metadata-log

• 元数据文件（metadata.json）的历史集合，以数组形式表示。
  

2. snap-xx.avro

清单列表文件，也称为快照文件，每次有数据（提交）写入时触发生成。

在该文件中主要记录了清单文件记录集，文件以avro的格式进行存储，每一条记录表示一个manifest，在每个记录中最主要的字段信息为"manifest_path"，标记清单文件的存储位置。

{
  "manifest_path": "hdfs://hdfsHACluster/user/hive/warehouse/iceberg_db.db/developer/metadata/051dc090-a770-441c-b76b-b97a591a97c7-m0.avro",
  "manifest_length": 6181,
  "partition_spec_id": 0,
  "added_snapshot_id": {
    "long": 8319024382941793184
  },
  "added_data_files_count": {
    "int": 2
  },
  "existing_data_files_count": {
    "int": 0
  },
  "deleted_data_files_count": {
    "int": 0
  },
  "partitions": {
    "array": [{
      "contains_null": false,
      "contains_nan": {
        "boolean": false
      },
      "lower_bound": {
        "bytes": "2023-02-10"
      },
      "upper_bound": {
        "bytes": "2023-03-10"
      }
    }]
  },
  "added_rows_count": {
    "long": 4
  },
  "existing_rows_count": {
    "long": 0
  },
  "deleted_rows_count": {
    "long": 0
  }
}

3. $COMMITUUID-m$COUNT.avro

（数据文件）清单信息，一个快照中可能包含了多个这样的文件信息。而在该文件中包含了涉及的多个数据文件信息。其中$COMMITUUID为提交的事务UUID，与快照文件中的COMMITUUID保持一致，$COUNT为清单文件的计数，从0开始。

该文件同样采用avro的格式进行存储，每一条记录描述一个具体的数据文件，在该记录中由三个字段组成：

• status

• 文件状态，0表示已存在、1表示新增、2表示删除

• snapshot_id

• 文件对应的快照ID

• data_file

• 文件详细信息，包括了文件路径，文件格式，以及文件中一些相关的metrics信息，例如记录数、列字段、最大最小值等。

  完整示例如下所示：

  {
    "status": 1,
    "snapshot_id": {
      "long": 8319024382941793184
    },
    "data_file": {
      "file_path": "hdfs://hdfsHACluster/user/hive/warehouse/iceberg_db.db/developer/data/birth=2023-02-10/00000-0-hadoop_20230313090641_733a351d-0554-4129-a56b-861f715638b9-job_1677482770597_0127-00002.parquet",
      "file_format": "PARQUET",
      "partition": {
        "birth": {
          "string": "2023-02-10"
        }
      },
      "record_count": 2,
      "file_size_in_bytes": 988,
      "block_size_in_bytes": 67108864,
      "column_sizes": {
        "array": [{
          "key": 1,
          "value": 54
        }, {
          "key": 2,
          "value": 60
        }, {
          "key": 3,
          "value": 103
        }]
      },
      "value_counts": {
        "array": [{
          "key": 1,
          "value": 2
        }, {
          "key": 2,
          "value": 2
        }, {
          "key": 3,
          "value": 2
        }]
      },
      "null_value_counts": {
        "array": [{
          "key": 1,
          "value": 0
        }, {
          "key": 2,
          "value": 0
        }, {
          "key": 3,
          "value": 0
        }]
      },
      "nan_value_counts": {
        "array": []
      },
      "lower_bounds": {
        "array": [{
          "key": 1,
          "value": "\u0002\u0000\u0000\u0000"
        }, {
          "key": 2,
          "value": "ma"
        }, {
          "key": 3,
          "value": "2023-02-10"
        }]
      },
      "upper_bounds": {
        "array": [{
          "key": 1,
          "value": "\u0004\u0000\u0000\u0000"
        }, {
          "key": 2,
          "value": "yuan"
        }, {
          "key": 3,
          "value": "2023-02-10"
        }]
      },
      "key_metadata": null,
      "split_offsets": {
        "array": [4]
      },
      "sort_order_id": {
        "int": 0
      }
    }
  } {
    "status": 1,
    "snapshot_id": {
      "long": 8319024382941793184
    },
    "data_file": {
      "file_path": "hdfs://hdfsHACluster/user/hive/warehouse/iceberg_db.db/developer/data/birth=2023-03-10/00000-0-hadoop_20230313090641_733a351d-0554-4129-a56b-861f715638b9-job_1677482770597_0127-00001.parquet",
      "file_format": "PARQUET",
      "partition": {
        "birth": {
          "string": "2023-03-10"
        }
      },
      "record_count": 2,
      "file_size_in_bytes": 990,
      "block_size_in_bytes": 67108864,
      "column_sizes": {
        "array": [{
          "key": 1,
          "value": 53
        }, {
          "key": 2,
          "value": 61
        }, {
          "key": 3,
          "value": 103
        }]
      },
      "value_counts": {
        "array": [{
          "key": 1,
          "value": 2
        }, {
          "key": 2,
          "value": 2
        }, {
          "key": 3,
          "value": 2
        }]
      },
      "null_value_counts": {
        "array": [{
          "key": 1,
          "value": 0
        }, {
          "key": 2,
          "value": 0
        }, {
          "key": 3,
          "value": 0
        }]
      },
      "nan_value_counts": {
        "array": []
      },
      "lower_bounds": {
        "array": [{
          "key": 1,
          "value": "\u0001\u0000\u0000\u0000"
        }, {
          "key": 2,
          "value": "chen"
        }, {
          "key": 3,
          "value": "2023-03-10"
        }]
      },
      "upper_bounds": {
        "array": [{
          "key": 1,
          "value": "\u0003\u0000\u0000\u0000"
        }, {
          "key": 2,
          "value": "jie"
        }, {
          "key": 3,
          "value": "2023-03-10"
        }]
      },
      "key_metadata": null,
      "split_offsets": {
        "array": [4]
      },
      "sort_order_id": {
        "int": 0
      }
    }
  }

  
  

  
  

  【场景分析】

  按照以往文章的惯例，我们还是通过一个实际场景，包括建表、到插入数据、修改列、删除分区的数据、删除快照等操作，元数据文件的变更等操作，对上面文件中一些关键字段进行剖析。

  1. 创建表

  表创建后，将元数据信息写入metadata.json文件中，但此时由于还没有数据，因此不会写入快照信息、数据清单文件。

  

  2. 插入数据

  该操作完成后写入了新的元数据文件（注意，ID自增），快照文件、数据清单文件、以及实际的数据文件。

  

  注意：建表时有指定分区，因此不同的记录数据存放在对应分区目录下。

  3. 对表schema进行变更，新增一个列字段

  由于没有数据的变化，因此只会新增一个元数据文件。

  

  4. 再次插入数据

  同样，数据是按照分区存放在不同的目录下，同时有新的清单文件记录本次操作新增的文件，而新的快照文件则同时引用两个清单文件，记录表的全量数据。元数据文件中记录了所有的快照信息，同时也记录当前使用的快照ID。

  

  5. 删除指定分区的数据

  对于数据的更新，默认采用写入合并记录的方式，因此，新的快照中只记录了两个新的清单文件，在这两个清单文件中分别记录不同的数据文件以及文件的状态。

  

  6. 再次写入数据

  流程和第4步操作一致，在上一个快照的基础上新增相关信息。

  

  7. 仅保留当前快照

  删除快照的同时，对于（当前保留的快照中）没有引用到的清单文件、以及标记为删除的数据文件，都会一起进行删除。

  

【总结】

简单小结一下，本文主要介绍了iceberg持久化的几个文件，以及文件的存储内容与格式，以及相互之间的关联关系，最后通过一个实际例子，分析了元数据文件的组织与变更。了解了这些内容，将有助于理解iceberg的数据读写流程，以及其他相关逻辑。

当然，文章中也提到了元数据文件格式的版本（v1，v2），不同版本对使用上也会有所区别。后面再单独讲解。

好了，这就是本文的全部内容，如果觉得本文对您有帮助，请点赞+转发，如果觉得有不正确的地方，也可以拍砖指点，最后，欢迎加我微信交流～