根据工具的支持情况选择格式
阅读约需 33分钟 分钟,11节中含5个示例。
读完本章后,你可以列出所有读取或写入你的表的工具,测量每个工具在其固定版本下的支持情况,并根据这些测量结果选择格式及其特性。
在第 1 章到第 9 章中,同一张表 wiki.pageviews_hourly 以三种格式走完了它的整个生命周期:Apache Iceberg、Delta Lake 和 DuckLake。每种格式以不同的方式完成相同的工作,而每个库只支持其中不同的一部分。你面对的选择并不是哪种格式在总体上最好,而是团队中的每个工具在你所运行的版本下,能否打开、修改并清理这种格式的表。本章说明如何进行这样的测量,给出本书所用固定版本下的测量结果,并提供一份简短的选择指南。
这一选择取决于读取方。在贯穿全书的案例 wiki.pageviews_hourly 中有三个读取方:一个通过 DuckDB 查询的仪表盘,一条通过 pyiceberg 追加数据的流水线,以及一个通过 deltalake 读取 Delta Lake 副本的归档作业。每个读取方都有各自的固定版本,并且每个都必须能打开其他读取方写入的数据。本章其余部分正是为这种情形做准备。
有三件事使这一选择比看上去更难。不同格式之间差异最大的特性,例如删除、重命名和分区变更,恰恰是团队最先需要的。每个库都按自己的节奏变化,因此一个工具在某个版本下能读取的表,换到另一个版本可能就打不开了。此外,在一台机器上通过的检查,并不能说明你的其他工具所运行的版本会怎样。本章各节将依次处理这三个问题。
先测量支持情况,再做选择
格式名称并不能说明一个工具支持什么。支持情况属于某个工具的某个版本:写入端可以创建读取端无法打开的特性,而供应商页面描述的是供应商自己的引擎,不是你笔记本电脑上的库。因此,应当从读取端出发,而不是从格式出发。写下将要读取该表的每一个工具及其版本,然后在每个版本上分别测试你计划使用的每一项特性。
下面的每项测量都从一个读取端出发,再在其上测试一项特性。pyiceberg 先对格式版本 2 的表执行一次删除,然后请求使用版本 3(iceberg-format-versions)。deltalake 启用删除向量,并将其读回(feature-check)。ducklake-catalog-version 示例会打印 DuckLake 目录的版本,ducklake-delete-files 和 ducklake-inlined-delete 示例则分别统计一次小规模删除和一次大规模删除之后的删除文件数量。每个示例对每个结果打印一行带标签的输出,因此你可以将输出与支持矩阵中的表格以及你自己的读取端进行对照。
表的负责人应当在运行读取端的机器上进行测量,而不是在版本各不相同的开发者笔记本电脑上。用一张小表记录结果,每个读取端占一行。各列依次为读取端、其固定版本、你的表所需的特性,以及测量日期。没有测量过的特性一律视为不支持,这条规则可以避免本章后面讨论的大多数故障。
| 读取端 | 固定版本 | 所需特性 | 测量日期 |
|---|---|---|---|
| pyiceberg | 0.12.0 | 格式版本 2 的写入、删除 | 你运行测量的日期 |
应将每一行输出视为一项结论,它只在某个工具的某个版本上成立。写入被拒绝的输出和写入成功的输出同样有用,因为拒绝结果会告诉你应当放弃哪个格式版本。捕获错误的示例只给出错误的类名,不给出错误消息,因此即使库改写了错误消息,输出也保持不变。
工作准则: 在选择格式版本或特性之前,先在每个读取端各自的固定版本上进行测量。记下每项结果及其测量时的版本。只要任何一个读取端的版本发生变化,就重新测量,并且不要沿用供应商页面上的支持表。
解读固定版本工具的行为
下表说明了固定版本的工具在本书运行中的行为。每一列对应一个工具:Iceberg 对应 pyiceberg,Delta Lake 对应 deltalake,DuckLake 对应 DuckDB 中的 DuckLake 扩展。固定的版本为 pyiceberg 0.12.0、deltalake 1.6.6 和 DuckDB 2.0.0。DuckDB 2.0.0 是长期支持版本,发布日期为 2026 年 10 月 21 日(DuckDB 发布日历)。DuckLake 1.0 于 2026 年 4 月 13 日发布(DuckLake 发布日历)。在这些固定版本下,目录报告的版本为 1.1,读者必须打开的就是这一版本。扩展的版本是另外一个版本:DuckDB 将其构建版本报告为 417a9117f5,而该扩展随 DuckDB 2.0.0 一同发布,因此其版本跟随 DuckDB 的版本。最后一列给出每个单元格所依据的示例或来源。此处未列出,表示本书存在空白,而不是缺少该功能。
1"""Attach a DuckLake catalog and print its catalog version, which readers must open, and the build of the DuckLake extension that DuckDB loaded. The point rests on the first printed line."""23from lib.lakehouse import attach_ducklake, connect_ducklake, new_warehouse456def main():7 with new_warehouse() as wh:8 con = connect_ducklake(wh.con)9 # the alias also names the catalog's metadata schema, which the next line reads10 attach_ducklake(con, "probe", wh.root)11 # the version is stored as a key and value row in the metadata table; the one row, first column12 version = con.execute("SELECT value FROM __ducklake_metadata_probe.ducklake_metadata WHERE key = 'version'").fetchall()[0][0]13 print("ducklake catalog version:", version)14 # a build hash, not a release number15 extension = con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name = 'ducklake'").fetchall()[0][0]16 print("ducklake extension version:", extension)171819if __name__ == "__main__":20 main()
python ducklake-catalog-version.pyducklake catalog version: 1.1
ducklake extension version: 417a9117f5
写入与读取版本
| 版本与读取 | pyiceberg | deltalake | DuckLake | 出处 |
|---|---|---|---|---|
| 将行作为提交写入 | 支持 | 支持 | 支持 | 三小时的数据落地 |
| 按编号读取较早的提交 | 支持,按快照 | 支持,按版本 | 支持,按快照 | Iceberg 部分,Delta 与 DuckLake 部分 |
| 创建格式版本 3 | 不支持,会抛出错误 | — | — | 示例 |
| 重命名列 | 支持,按字段 ID | 不支持,静默地不执行任何操作 | 此处未演示 | Iceberg 部分,deltalake 部分 |
| 创建时设置列映射 | — | 支持 | — | deltalake 部分 |
变更与清理
| 变更与清理 | pyiceberg | deltalake | DuckLake | 出处 |
|---|---|---|---|---|
| 删除行 | 重写数据文件 | 重写数据文件 | 写入删除文件 | 第 5 章 |
| 是否写入删除文件 | 否 | 否 | 是,内联时除外 | 格式版本、功能检查、DuckLake、内联 |
| 更新插入或合并 | 更新插入,产生多个快照 | 此处未展示 | MERGE INTO |
更新插入、合并语句 |
| 变更分区 | 旧文件沿用旧的分区规范 | 以 schema 模式覆盖写入 | 使用 ALTER TABLE 变更 |
第 4 章、其他格式 |
| 压缩小文件 | 没有对应方法;需覆盖写入整张表 | optimize.compact() |
合并相邻文件 | Iceberg、deltalake、DuckLake |
| 过期快照 | 按快照标识或 older_than 指定;不删除任何文件 |
按保留期清理 | 先使快照过期,再清理文件 | Iceberg、deltalake、DuckLake |
1"""Load six hours into a DuckLake table with data inlining off, then count the delete files that a small and a large delete write. The point rests on the delete-file line after the small delete."""23from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, new_warehouse, read_cut_hour45LOW_VIEWS = 180 # few rows of hour 02 fall below this6VERY_LOW_VIEWS = 1000 # most of the table's rows fall below this789def delete_files(con):10 # one row per data file, so the rows with a delete file count the files a delete touched11 return con.execute(f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "12 "WHERE delete_file IS NOT NULL").fetchall()[0][0]131415def main():16 with new_warehouse() as wh:17 con = connect_ducklake(wh.con)18 # 0 turns inlining off, so a delete is written as a delete file rather than kept in the catalog19 create_ducklake_table(con, wh.root, inlining_row_limit=0)20 table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"21 for hour in range(6):22 con.register("hour", read_cut_hour(hour))23 con.execute(f"INSERT INTO {table} SELECT * FROM hour")24 con.unregister("hour")2526 con.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")27 print("rows left after the small delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])28 print("delete files after the small delete:", delete_files(con))2930 # no hour filter, so this delete reaches all six hours31 con.execute(f"DELETE FROM {table} WHERE views < {VERY_LOW_VIEWS}")32 print("rows left after the large delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])33 print("delete files after the large delete:", delete_files(con))343536if __name__ == "__main__":37 main()
python ducklake-delete-files.pyrows left after the small delete: 2995
delete files after the small delete: 1
rows left after the large delete: 195
delete files after the large delete: 6
1"""Repeat `ducklake-delete-files` with DuckLake's default inlining, to show that the small delete writes no delete file. The point rests on the delete-file line after the small delete."""23from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, new_warehouse, read_cut_hour45LOW_VIEWS = 180 # few rows of hour 02 fall below this6VERY_LOW_VIEWS = 1000 # most of the table's rows fall below this789def delete_files(con):10 # one row per data file, so the rows with a delete file count the files a delete touched11 return con.execute(f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "12 "WHERE delete_file IS NOT NULL").fetchall()[0][0]131415def main():16 with new_warehouse() as wh:17 con = connect_ducklake(wh.con)18 # None keeps DuckLake's default inlining; ducklake-delete-files passes 0 to turn it off19 create_ducklake_table(con, wh.root, inlining_row_limit=None)20 table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"21 for hour in range(6):22 con.register("hour", read_cut_hour(hour))23 con.execute(f"INSERT INTO {table} SELECT * FROM hour")24 con.unregister("hour")2526 con.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")27 print("rows left after the small delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])28 print("delete files after the small delete:", delete_files(con))2930 # no hour filter, so this delete reaches all six hours31 con.execute(f"DELETE FROM {table} WHERE views < {VERY_LOW_VIEWS}")32 print("rows left after the large delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])33 print("delete files after the large delete:", delete_files(con))343536if __name__ == "__main__":37 main()
python ducklake-inlined-delete.pyrows left after the small delete: 2995
delete files after the small delete: 0
rows left after the large delete: 195
delete files after the large delete: 6
目录与 DuckDB
DuckDB 自带的 delta 扩展与 deltalake 是两条不同的路径。它可以写入 Delta Lake 表,下文的决策指南会对此加以说明。
工作准则: 请对照每个单元格所指明的示例或来源来阅读它。没有示例支撑的单元格,只是一个需要在你自己的读者身上检验的论断,不能直接依赖。
pyiceberg 不写入版本 3 的表
Iceberg 规范的版本 3 一节将二进制删除向量定为行级删除格式。该节指出:“写入器不得向 v3 表添加新的位置删除文件”(Iceberg spec)。同一节还为新行加入了行谱系、列默认值、variant 类型和纳秒级时间戳。
1"""Create a format version 2 Iceberg table, delete rows from it, then ask pyiceberg for format version 3. The point rests on the last printed line, which shows the refusal."""23from pyiceberg.expressions import LessThan45from lib.lakehouse import create_iceberg_table, new_warehouse, read_cut_hour, scan_arrow67LOW_VIEWS = 180 # about one row in six of hour 00 falls below this8910def main():11 with new_warehouse() as wh:12 table = create_iceberg_table(wh, properties={"format-version": "2"}) # table properties are strings, so the version is quoted13 table.append(read_cut_hour(0))14 print("format version:", table.metadata.format_version)1516 # scan_arrow reads the current snapshot, so the count moves with each commit17 before = scan_arrow(table).num_rows18 table.delete(LessThan("views", LOW_VIEWS))19 print("rows deleted:", before - scan_arrow(table).num_rows)20 # content 0 marks a data file; any other value marks a delete file21 contents = table.inspect.files().column("content").to_pylist()22 print("delete files after the delete:", sum(1 for content in contents if content != 0))23 for number, snapshot in enumerate(table.metadata.snapshots, start=1):24 print(f"snapshot {number} operation:", snapshot.summary.operation.value)2526 # pyiceberg refuses version 3 by raising, so the refusal is caught here and its class printed27 try:28 create_iceberg_table(wh, identifier="wiki.format_three", properties={"format-version": "3"})29 except NotImplementedError as exc:30 print("format version 3 create:", type(exc).__name__)31 else:32 print("format version 3 create: created")333435if __name__ == "__main__":36 main()
python iceberg-format-versions.pyformat version: 2
rows deleted: 82
delete files after the delete: 0
snapshot 1 operation: append
snapshot 2 operation: overwrite
format version 3 create: NotImplementedError
在当前固定的版本下,pyiceberg 写入的是格式版本 2。该示例请求版本 2,并打印其表的版本,即 2。请求格式版本 3 会引发 NotImplementedError,因此这个写入器无法使用任何版本 3 的特性。
在这些固定版本下,pyiceberg 通过重写所涉及的数据文件来删除数据,尽管格式版本 2 也允许使用删除文件(第 5 章)。该表减少了 82 行,并包含 0 个删除文件。它的两个快照分别是一个 append,以及针对删除操作的一个 overwrite。在做出选择之前,请在你自己表的副本上衡量这种重写的开销。
| 特性 | Iceberg v3 规范 | 这些固定版本下的 pyiceberg |
|---|---|---|
| 二进制删除向量 | 行级删除格式 | 不写入 |
| 位置删除文件 | 旧格式,仅见于格式版本 2 的表 | 不写入 |
| 行谱系、默认值、variant、纳秒级时间戳 | 属于版本 3 | 不可用:没有版本 3 的表 |
工作准则: 在这些固定版本下,用 pyiceberg 写入格式版本 2,并且不要向任何读取方承诺版本 3 的特性。只有当你使用的写入器能创建版本 3,且你的读取方全部都能打开它时,才选择版本 3,并分别在它们各自的固定版本上核对这两点。
删除向量需要升级协议
Delta Lake 协议在其链接所指明的发布标签处规定,带有删除向量的表需要读取器版本 3 和写入器版本 7,并且两份特性列表中都要包含 deletionVectors 特性。协议还规定,读取器在读取该表之前,必须实现读取器列表中的每一项特性(Delta protocol)。Delta 表协议中的读取器特性是对所有读取器作出的承诺:每个读取器都必须能处理该特性,因此缺少该特性的读取器无法正确读取这张表。
1"""Turn on deletion vectors in a Delta Lake table, delete the rows below 180 views, and print the protocol the table declares. The point rests on the reader features line, which lists what a reader must implement."""23from deltalake import DeltaTable, write_deltalake45from lib.lakehouse import new_warehouse, read_cut_hour, read_delta67LOW_VIEWS = 180 # about one row in six of hour 00 falls below this8910def deletion_vector_files(path):11 """Count files under the table folder that are not Parquet or the Delta log."""12 # the log holds JSON commits and checkpoints, not deletion vectors, so it is skipped13 return sum(1 for item in path.rglob("*")14 if item.is_file() and item.suffix != ".parquet" and "_delta_log" not in item.parts)151617def main():18 with new_warehouse() as wh:19 path = wh.root / "dv_table"20 # delta.enableDeletionVectors is the table property that turns deletion vectors on, set when the table is written21 write_deltalake(str(path), read_cut_hour(0), configuration={"delta.enableDeletionVectors": "true"})22 table = DeltaTable(str(path))23 protocol = table.protocol()24 print("minimum reader version:", protocol.min_reader_version)25 print("minimum writer version:", protocol.min_writer_version)26 # sorted so the printed list reads the same on every run27 print("reader features:", ", ".join(sorted(protocol.reader_features)))2829 # read_delta reads through deltalake's QueryBuilder, the only Delta read path in this book30 before = read_delta(str(path)).num_rows31 metrics = table.delete(f"views < {LOW_VIEWS}")32 print("rows deleted:", before - read_delta(str(path)).num_rows)33 # the delete's num_removed_files metric, which counts the data files it replaced34 print("data files rewritten:", metrics["num_removed_files"])35 print("rows through QueryBuilder:", read_delta(str(path)).num_rows)36 print("deletion vector files:", deletion_vector_files(path))373839if __name__ == "__main__":40 main()
python feature-check.pyminimum reader version: 3
minimum writer version: 7
reader features: deletionVectors, timestampNtz, variantType
rows deleted: 82
data files rewritten: 1
rows through QueryBuilder: 417
deletion vector files: 0
开启该设置会改变读取器必须支持的内容。一旦开启,这张表就声明最低读取器版本为 3、最低写入器版本为 7。它的读取器特性为 deletionVectors, timestampNtz, variantType,读取器必须实现其中的每一项。我们只设置了删除向量这一项设置,因此 deltalake 自行添加了其余两项特性。
在这个固定版本下,deltalake 声明了该特性,但删除时仍然采用重写文件的方式。对浏览量低于 180 的行执行删除,共删除了 82 行,重写了 1 个数据文件,而表中的删除向量文件数为 0。随后 QueryBuilder 读取到 417 行。本书只通过 QueryBuilder 读取 Delta 表,如第 8 章所示。
列表中的每一项特性都很重要,不只是删除向量。缺少 timestampNtz 或 variantType 的读取器,与缺少 deletionVectors 的读取器面临同样的问题。每次变更之后,都应把打印出的特性列表与各读取器自己的列表逐一比对。
因此,开启删除向量设置对这张表的每一个读取器而言都是一次协议变更,而且写入会在任何读取器接受测试之前就已成功。只有当读取集合中的每个读取器都实现了 deletionVectors 特性时,才应开启它;否则继续使用写时复制。
这里所说的读取器检查,是指在第一次生产写入之前,通过读取器自己的接口打开这张表。对于本案例中的 Delta Lake 副本,该检查就是通过 QueryBuilder 读取数据,并读取协议,两者都在 feature-check 示例中。
工作准则: 只有在核实了每个读取器在其自身版本上的特性支持之后,才启用删除向量。每次变更后都要回读该表的协议;对于可能被测试集合之外的读取器打开的表,继续使用写时复制。
新建表的检查清单
在创建一张将被多个工具打开的表之前,请先过一遍这份清单。每一项都针对支持矩阵和删除向量一节中显示出的一项风险。
- 列出每一个读取方和写入方,并注明其版本。清单中遗漏的工具,就是一个未经测试的读取方,而出问题的往往正是它。
- 对表所需的每项特性,在每个工具上测量其支持情况,如本章的示例所做的那样。要测量读取方,而不仅仅是写入方,因为写入成功只能证明写入方能够生成这些文件。
- 有意识地设定格式版本和协议。把它们打印出来核对,并用每个读取方读取这张表。不要接受自己没有选择过的默认值。
- 拒绝使用集合中任何一个读取方不支持的格式版本或特性。只要有一个读取方无法打开这张表,就是一次服务中断,无论这些特性对其他读取方有多大好处。
- 只有在测得的支持情况允许时,才承诺支持重命名。Iceberg 按字段 ID 重命名。在这些固定版本下,deltalake 不支持重命名,因此应改为计划一次重写,并在事后检查列名。
- 除非每个读取方都已用删除向量测试过,否则应为删除操作保留普通的写时复制路径。写时复制的代价是要重写文件,但它在所有工具上都能打开。
- 按以下顺序规划任何升级:先升级读取方,再升级写入方,最后升级协议。每一步之后都要读取这张表,一旦有读取方失败就停止。
- 每次固定版本变更时,都重新运行这些测量,并把新的版本记录到读取方表中。
工作准则: 把这份清单与表的设计说明放在一起,这样下一个新增读取方的人就能从同一份记录出发。持续更新一份清单的成本,低于在读取失败之后重建一份清单。
根据读者选择格式
请在测量完读者之后使用本指南。第一列是情形,而不是格式。它把已测量的读者集合对应到某种格式,但不能代替测量。
| 如果你的情形是 | 选择 | 原因 |
|---|---|---|
| pyiceberg 和 DuckDB 读取该表 | Iceberg,格式版本 2 | pyiceberg 能读取它,DuckDB 能查询其输出 |
| 有多个读者,且需要原地重命名 | Iceberg | 重命名会保留字段 ID,如第 3 章所示 |
| DuckDB 是唯一的引擎,且希望用 SQL 做变更 | DuckLake | 删除、合并和分区变更都以 SQL 运行 |
| Delta 表已经存在,且 deltalake 能读取 | 保留 Delta Lake,不承诺重命名 | 通过覆盖来更改分区,并在每次更改后回读 |
| 希望用 DuckDB 修改 Delta 表 | 在这些固定版本下不可行 | DuckDB 只能追加;更新和删除请使用 deltalake |
DuckDB 的 delta 扩展可以写入 Delta Lake 表。所固定发布版本 2.0.0 的 DuckDB 文档指出,它可以创建表并向其追加数据,同时将 UPDATE、DELETE、MERGE INTO、ALTER TABLE 和 DROP TABLE 列为不支持(DuckDB delta 文档,限制)。本书没有任何示例运行该扩展。这些示例在运行时不安装任何内容,而是使用各格式自带的库,因此读者看到的正是写入该表的同一个库,并且示例运行期间不会下载任何内容。
请逐行阅读这张表。当两行指向不同方向时,由读者决定。先选择已测量集合中每个读者都能打开的格式,再选择每个读者都支持的特性。
将本指南应用到贯穿全书的案例。仪表盘和流水线都用 pyiceberg 或 DuckDB 打开 pageviews 表,这指向 Iceberg 格式版本 2。归档作业读取的是 Delta Lake 副本,因此 Delta 这一行只适用于该副本,且该副本以写时复制的方式处理删除。
对于由多个工具读取的表,我们推荐将 Iceberg 格式版本 2 作为默认选择,因为 pyiceberg 能写入它,DuckDB 能读取其输出,而且示例对两者都做了测量。它在这些固定版本下的代价是:每次删除都会重写所涉及的数据文件,表需要一个目录,并且 pyiceberg 没有压缩或孤立文件清理的调用。当 DuckDB 是唯一的引擎时,我们推荐 DuckLake,因为读取方和写入方共用同一个 SQL 接口。它的代价是:读者仅限于 DuckDB,目录版本与 DuckDB 发布版本绑定,并且除非关闭内联,小规模删除会被内联处理。如果本章中的检查表明某个读者无法完成你所需要的操作,则应做出不同的选择。
工作准则: 选择已测量集合中每个读者都能打开的格式,然后只选择该集合支持的特性。如果没有任何格式能满足所有需求,就拆分该表或更换读者。不要向读者承诺测量没有覆盖的特性。
生产环境中会出什么问题
共享湖仓中的大多数格式故障,源于写入方没有测试过的某个工具,而不是格式本身的缺陷。这里的每一种故障,前面的某一节都测量过或引用过,因此你可以在自己的表中逐一检查。
依据厂商声明做选择。 支持说明页描述的是某一个引擎,而且版本往往与你使用的不同。应当用它来确定要测试什么,而不是把它当作答案。请对照你自己的固定版本核实该声明。
只测试一个引擎。 一张表可能由某个库写入,再由另一个不支持同一特性的库读取。写入在一个工具中成功,而故障要到第二个工具打开这张表时才出现。请在第一次写入之前,对集合中的每个工具运行读取方检查。
读取方没有实现的特性。 删除向量设置会给表增加一项读取方特性,而协议要求读取方实现它。你的工具集合之外的读取方可能能打开这张表,却在这项特性上失败。应当从协议记录中查明这一点,特性检查示例会打印该记录,而不要等到后来的查询报错。
什么都不做的重命名。 在这些固定版本下,deltalake 的 set_column_metadata 调用不报错就返回,并且会提升版本号,但列名保持不变。第 3 章展示了这个陷阱。检查的办法是在变更之后读取列名。
以错误的顺序升级。 写入方如果先于读取方升级,可能产生读取方无法打开的表,而最先出现的迹象是另一个团队的作业读取失败。检查清单中的顺序能让每个读取方在每一步都能打开这张表。
以写入结果判断一张表。 写入成功只说明写入方能够生成这些文件,并不说明其他工具能够读取它们。本章中的删除向量检查先写入、再删除、然后统计读取方的特性数量,原因正在于此。
用统计行数检查 DuckLake 的删除。 在 DuckLake 默认的内联方式下,只删除几行的小型删除不会写出删除文件,而同样的删除在关闭内联时会写出一个。统计行数的检查在两种情况下都会说删除成功了。还应像 DuckLake 删除示例那样统计删除文件。
随 DuckDB 变动的目录版本。 在这些固定版本下,DuckLake 目录报告的版本是 1.1,而打开它的扩展报告的构建是 417a9117f5。DuckLake 文档指明了 1.1 版所要求的 DuckDB 发行版(DuckLake 文档)。较旧的 DuckDB 可能无法打开该目录,因此一次升级可能破坏一个本身没有变化的读取方。
工作准则: 在写入、升级或依赖厂商声明之前,先在每个读取方各自的固定版本上进行测量。升级写入方或目录时,应保留旧版本,直到每个读取方都打开过升级后的结果。
本章的决定
- 我们推荐在这些固定版本下使用 Iceberg 格式版本 2 和 pyiceberg。我们不向任何读者承诺支持格式版本 3,也不设定改变这一点的日期。由固定版本决定,由测量结果证明。
- 我们按这些固定版本下的实测结果给出支持矩阵,每个单元格都指向一个示例或一个有引用的来源。
- 我们不在读者可能用测试范围之外的工具打开的表中使用删除向量。
- 在这些固定版本下,我们不承诺 deltalake 表支持重命名。
- 我们既统计 DuckLake 的删除文件,也统计行数。
- 我们把未经测量的特性视为不支持,因为本章所有的失败都源于某人想当然认为已支持的特性。
- 我们把 DuckLake 目录版本与扩展版本分开说明。目录版本决定哪些读取器能打开该目录,而扩展版本跟随 DuckDB。
- 我们选择实测的矩阵,而不是供应商的支持页面,因为是固定的版本决定了什么能够打开。
- 以 Iceberg 格式版本 2 作为默认值是一种判断,并已标明为判断。支撑它的测量结果就是各个示例,也是需要重新运行的部分。
- 本书不运行 DuckDB 的
delta或iceberg扩展。书中的示例在运行时不安装任何东西,并使用各格式自己的库。DuckDB 的delta扩展可以写入 Delta Lake 表,其文档对此有说明。
本章,在本版次中
版次 2026.11.10示例于 2026年11月20日 通过本章 5个示例 个示例中有 5 个通过
译自英文版图书,版次 2026.11.10。