從工具支援的功能選擇格式
閱讀約需 35 分鐘 分鐘,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 會啟用刪除向量(deletion vectors),再將其讀回(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 發布行事曆)。在這些固定版本下,目錄(catalog)回報的版本為 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 |
更新插入、合併語法 |
| 變更分割方式 | 舊資料檔沿用舊的分割規格 | 以結構描述模式覆寫 | 以 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 版一節,將二元刪除向量(binary deletion vector)定為列級刪除格式。該節指出「寫入端不得在 v3 資料表中新增位置刪除檔」(Iceberg spec)。同一節還加入了新資料列的列譜系(row lineage)、欄位預設值、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 功能時,才開啟它;否則請維持寫入時複製(copy-on-write)。
本文所稱的讀取端檢查,是指在第一次正式環境寫入之前,透過讀取端自身的介面開啟資料表。對於此案例中的 Delta Lake 副本,這項檢查就是透過 QueryBuilder 讀取資料,並讀取其協定,兩者都在 feature-check 範例中。
實用原則: 只有在以各讀取端自己的版本檢查過其功能支援之後,才啟用刪除向量。每次變更後都要回頭讀取資料表的協定,而且凡是可能由測試範圍之外的讀取端開啟的資料表,都應維持寫入時複製。
新資料表檢查清單
在建立一個會被多個工具開啟的資料表之前,請先使用這份清單。每一項都針對支援矩陣與刪除向量一節所顯示的一項風險。
- 列出每一個讀取端與寫入端,並註明其版本。未列入清單的工具,就是尚未測試的讀取端,而出問題的往往就是它。
- 針對資料表所需的每一項功能,如本章的範例所示,逐一量測各工具的支援情形。要量測讀取端,而不只量測寫入端,因為寫入成功只能證明寫入端能產生檔案。
- 刻意設定格式版本與協定。把它們印出來確認,並以每一個讀取端讀取該資料表。不要接受自己沒有選擇的預設值。
- 拒絕使用集合中任何一個讀取端不支援的格式版本或功能。只要有一個讀取端無法開啟資料表,就是一次服務中斷,不論這些功能對其他讀取端有多好。
- 只在量測到的支援允許時,才承諾可以重新命名。Iceberg 依欄位 ID 進行重新命名。deltalake 在這些固定版本下沒有重新命名功能,因此應改為規劃重寫,並在事後檢查欄位名稱。
- 除非每一個讀取端都已用刪除向量測試過,否則刪除作業請保留單純的寫入時複製(copy-on-write)路徑。寫入時複製的代價是要重寫檔案,但它在各處都能開啟。
- 依下列順序規劃任何升級:先升級讀取端,再升級寫入端,最後升級協定。每一步之後都要讀取資料表,若有讀取端失敗就停止。
- 每次固定版本變更時,都要重新執行量測,並把新的版本記錄在讀取端表格中。
實用原則: 請把這份清單與資料表的設計說明放在一起,讓下一位新增讀取端的人從同一份記錄開始。持續更新清單的成本,低於讀取失敗後才重建清單的成本。
依讀取端選擇格式
請在量測完讀取端之後再使用本指南。第一欄是情境,而不是格式。本指南把量測出的讀取端組合對應到某個格式,但不能取代量測本身。
| 如果你的情境是 | 選擇 | 原因 |
|---|---|---|
| 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 docs, Limitations)。本書沒有任何範例執行這個擴充套件。這些範例在執行時不安裝任何東西,並使用各格式自己的函式庫,因此讀者看到的是實際寫入該資料表的同一個函式庫,而且範例執行期間不會下載任何內容。
請逐列閱讀此表。當兩列指向不同方向時,由讀取端決定。請先選擇你量測出的讀取端組合中每個讀取端都能開啟的格式,再選擇每個讀取端都支援的功能。
接著把本指南套用到貫穿全書的案例。儀表板與管線都以 pyiceberg 或 DuckDB 開啟 pageviews 資料表,這指向 Iceberg 格式版本 2。封存工作讀取的是 Delta Lake 副本,因此 Delta 那一列只適用於該副本,而且該副本的刪除以 copy-on-write 方式處理。
對於由多個工具讀取的資料表,我們建議預設採用 Iceberg 格式版本 2,因為 pyiceberg 能寫入它,DuckDB 能讀取其輸出,而且範例對兩者都做了量測。它在這些版本下的代價是:每次刪除都會重寫所涉及的資料檔案,資料表需要目錄(catalog),而且 pyiceberg 沒有壓縮(compaction)或孤立檔案清理的呼叫。當 DuckDB 是唯一的引擎時,我們建議採用 DuckLake,因為讀取端與寫入端共用同一套 SQL 介面。它的代價是:讀取端僅限於 DuckDB,目錄版本與 DuckDB 的發行版綁在一起,而且除非關閉內嵌(inlining),否則小型刪除會被內嵌。當本章的檢查顯示某個讀取端無法做到你所需要的事時,請做出不同的選擇。
實用原則: 選擇你量測出的讀取端組合中每個讀取端都能開啟的格式,然後只選擇該組合所支援的功能。如果沒有任何格式能滿足所有需求,就拆分資料表或更換讀取端。不要向讀取端承諾量測結果未涵蓋的功能。
正式環境中會出什麼問題
共用 lakehouse 中的多數格式失敗,來自寫入端未測試過的工具,而不是格式本身的錯誤。這裡的每一項失敗,都是前面某一節量測過或引用過的,因此你可以在自己的資料表中檢查。
依廠商說法選擇。 支援說明頁面描述的是單一引擎,而且版本常與你使用的不同。請用它來找出該測試什麼,不要把它當成答案。請對照你自己的鎖定版本來檢查該說法。
只測試一個引擎。 資料表可能由某個函式庫寫入,卻由另一個不支援相同功能的函式庫讀取。寫入在一個工具中成功,等到第二個工具開啟資料表時才出現失敗。請在第一次寫入之前,對組合中的每個工具執行讀取端檢查。
讀取端未實作的功能。 刪除向量(deletion vector)設定會為資料表加上一項讀取端功能,而協定要求讀取端必須實作它。組合之外的讀取端可能開得了資料表,卻在這項功能上失敗。請從協定記錄得知這一點,這份記錄由功能檢查範例印出,不要等到後來的查詢錯誤才發現。
毫無作用的重新命名。 在這些鎖定版本下,deltalake 的 set_column_metadata 呼叫不會出錯就返回,也會使版本號增加,但欄位名稱維持不變。第 3 章展示了這個陷阱。檢查方式是在變更之後讀取欄位名稱。
以錯誤的順序升級。 寫入端若走在讀取端之前,可能產生讀取端無法開啟的資料表,而第一個徵兆是另一個團隊的作業讀取失敗。檢查清單中的順序,能讓每個讀取端在每一步都能開啟資料表。
以寫入結果判斷資料表。 寫入成功只表示寫入端能產生檔案,並不表示其他工具能讀取這些檔案。本章的刪除向量檢查先寫入、刪除,再計算讀取端的功能數量,正是為了這個原因。
以資料列數檢查 DuckLake 的刪除。 在 DuckLake 預設的內嵌(inlining)設定下,只刪除幾列的小型刪除不會寫出刪除檔,而關閉內嵌後同樣的刪除會寫出一個。只計算資料列數的檢查,在兩種情況下都會說刪除成功。請像 DuckLake 刪除範例那樣,一併計算刪除檔的數量。
隨 DuckDB 變動的目錄版本。 在這些鎖定版本下,DuckLake 目錄回報的版本是 1.1,而開啟它的擴充套件回報的建置是 417a9117f5。DuckLake 文件指出了 1.1 版所需的 DuckDB 發行版本(DuckLake 文件)。較舊的 DuckDB 可能無法開啟該目錄,因此升級可能使一個本身沒有變動的讀取端失效。
實用原則: 在寫入、升級或採信廠商說法之前,先在每個讀取端各自的鎖定版本上量測。升級寫入端或目錄時,請保留舊版本,直到每個讀取端都成功開啟結果為止。
本章所做的決定
- 我們建議在這些固定版本的 pyiceberg 上使用 Iceberg 格式版本 2。我們不向任何讀者承諾支援格式版本 3,也不訂定改變的日期。由固定的版本決定,並由量測結果證明。
- 我們以這些固定版本下的實測結果來陳述相容性矩陣,每個儲存格都指向一個範例或一份引用的來源。
- 我們不在測試範圍以外的讀者會開啟的資料表中使用刪除向量(deletion vector)。
- 在這些固定版本下,我們不承諾 deltalake 資料表可以重新命名。
- 我們除了計算資料列,也計算 DuckLake 的刪除檔案。
- 我們把未經量測的功能視為不支援,因為本章的失敗全都來自有人自行假設已支援的功能。
- 我們將 DuckLake 目錄(catalog)版本與擴充套件版本分開陳述。目錄版本決定哪些讀取端能開啟該目錄,擴充套件版本則跟隨 DuckDB。
- 我們選擇實測的矩陣,而不採用廠商的支援頁面,因為決定能否開啟的是固定下來的版本。
- 以 Iceberg 格式版本 2 作為預設值是一項判斷,並已標明為判斷。支撐這項判斷的量測就是各範例,也是應該重新執行的部分。
- 本書不執行 DuckDB 的
delta或iceberg擴充套件。書中的範例在執行時不安裝任何東西,並使用各格式自己的函式庫。如其文件所述,DuckDB 的delta擴充套件可以寫入 Delta Lake 資料表。
本章,於本版次中
版次 2026.11.10範例於 2026年11 月 20 通過測試本章 5 個範例 個範例中有 5 個通過
譯自英文書,版次 2026.11.10。