在目錄中註冊資料表,並從 DuckDB 查詢

閱讀約需 38 分鐘 分鐘,8 節 中共有 5 個範例。

版次 2026.11.10 範例於 2026年11 月 20 通過測試 39 個範例中有 39 個通過 變更內容

由 AI 翻譯。經人工以英文驗證。 我們如何製作書籍

譯自英文書,版次 2026.11.10。 閱讀原文

在本章中,你會在 SQL 目錄(catalog)中註冊一張 Iceberg 資料表,掛載一個 DuckLake 目錄,依路徑開啟一張 Delta Lake 資料表,並執行一條 DuckDB 陳述式,將 Iceberg 的一張資料表與 DuckLake 的一張資料表進行 join。你也會了解各個目錄各自保存哪些內容,以及當目錄與資料檔案彼此不一致時,資料表會發生什麼事。

前面各章以各自的途徑開啟每張資料表:Iceberg 使用目錄物件,DuckLake 使用檔案,Delta Lake 使用資料夾。第一張資料表已將 wiki.pageviews_hourly 以名稱 local 註冊在 Iceberg SQL 目錄中。本章說明這個名稱的作用,以及各種格式以什麼來取代它。本章也新增第二張資料表 wiki.domains,這是一份包含 4 列的清單,記錄網域代碼及各網域所使用的語言。這張資料表存放在 DuckLake 目錄中,join 一節會將它與 Iceberg 的頁面瀏覽量資料表進行 join。

目錄存放什麼

最近一次變動於第 2026.11.10 版

若問 wiki.pageviews_hourly 存放在哪裡,答案取決於所用的格式。在底層,每種格式都把資料表儲存為資料檔案加上中繼資料檔案。中繼資料記錄資料表的目前狀態:其綱要、分割區規格,以及(直接或透過清單檔)目前快照或版本所含的資料檔案。每次提交都會寫入新的中繼資料,並讓資料表移到該中繼資料。目錄則是一份登錄表,把資料表名稱對應到其目前中繼資料所在的位置。讀取端向目錄查詢 wiki.pageviews_hourly,會得到一個指向中繼資料的指標,接著再讀取中繼資料所列出的資料檔案。

目錄保存的是指標,而不是資料列。Parquet 檔案仍留在倉儲資料夾中,目錄只說明該從哪裡開始讀取。名稱還有第二層:wiki 是一個命名空間,本書中每個 Iceberg 資料表名稱,都是由命名空間與資料表名稱以點號連接而成。

選擇目錄可歸結為兩個問題:誰寫入資料表,以及誰讀取資料表。由單一作業寫入、單一引擎讀取的資料表,可以放在以檔案為基礎的目錄中,並憑路徑找到。由多個引擎讀取的資料表,則需要一個每個引擎都能解析的名稱,這正是 SQL 目錄或某項服務所提供的。我們建議每個資料表只使用一個目錄,並在資料表旁留下一份紀錄,載明其目錄與負責人。如連接一節所示,跨目錄的聯結可以在同一個工作階段中進行,但這並不會讓兩個目錄變成同一個。

本書的三種格式使用三種不同的目錄:

格式 以什麼命名資料表 目前的中繼資料位於何處
Iceberg 一個 SQL 目錄物件,此處命名為 local 目錄的資料庫,其中指向中繼資料檔案
DuckLake 以路徑附加的目錄檔案 目錄檔案內部
Delta Lake 無;以資料表的資料夾路徑為準 資料表的資料夾中

Iceberg REST 目錄是另一種類型的目錄,它是一項服務,而非檔案。其 REST 目錄頁面描述了一套以 OpenAPI 規範的通用 API,可與任何 Iceberg 目錄互動,使用者端只需一種實作即可對應所有目錄。同一頁面指出,該協定採用以變更為基礎的提交,因此服務可在其端解決衝突並重試,且根中繼資料由目錄服務寫入。本章不執行 REST 目錄,因為每一個都需要一項執行中的服務,而這裡的範例是在離線、不含任何服務的情況下執行的。本書也不比較實作此協定的各種產品。

目錄所保存的可以不只是名稱。分類與保存規則同樣屬於資料表的中繼資料。Data Governance as Code對此有所討論,本書則不教授這些內容。

**實用原則:**在寫入資料表之前,先查明是哪個目錄或路徑為它命名,並且將該目錄與資料資料夾一併備份。Parquet 檔案並不會為資料表命名,命名的是目錄,如故障一節所示。

在 SQL 型目錄中註冊資料表

最近一次變動於第 2026.11.7 版

pyiceberg 的 SqlCatalog 將資料表存放在資料庫中。你需要為該資料庫提供 uri,並為寫入資料檔與中繼資料的資料夾提供 warehouse。本書使用 SQLite 檔案作為資料庫,並以本機資料夾作為倉儲。pyiceberg 設定頁面指出,SQL 型目錄背後需要一個資料庫,並警告 SQLite 並非為並行存取而設計,適合用於探索或開發。這些範例屬於開發用途,因此這項限制不會影響其中任何內容。正式環境的目錄需要可供多個寫入者使用的資料庫。

下一個範例會以相同名稱再次開啟同一個目錄檔案,並透過第二個物件讀取該資料表。接著,它會為該資料表的中繼資料註冊第二個名稱,並顯示名稱不同的目錄物件能看到什麼。

register-iceberg-table.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Register an Iceberg table in a SQL catalog, then reach it through a second catalog object, a stale object and asecond name. The point rests on the 'loaded object' and 'after a reload' lines, and the last line shows what anobject under another catalog name can see."""from lib.lakehouse import (ICEBERG_ID, NAMESPACE, create_iceberg_table, new_warehouse,                           open_catalog, read_cut_hour, safe_error, scan_arrow)with new_warehouse() as wh:    table = create_iceberg_table(wh)    for hour in range(3):                                # hours 0, 1 and 2 of the cut, one commit each        table.append(read_cut_hour(hour))    # A second object with the same catalog name sees the same tables.    same = open_catalog(wh)                              # the default name, local, as the first object had    loaded = same.load_table(ICEBERG_ID)    print("rows read through the second object:", scan_arrow(loaded).num_rows)    # A loaded table is a snapshot of the catalog as it was when loaded.    stale = same.load_table(ICEBERG_ID)    table.append(read_cut_hour(3))                       # the fourth hour, committed after stale was loaded    print("rows in the loaded object after another append:", scan_arrow(stale).num_rows)    print("rows after a reload:", scan_arrow(same.load_table(ICEBERG_ID)).num_rows)    # Register the same metadata file under a new name: a pointer, not a copy.    same.create_namespace("archive")    same.register_table("archive.pageviews_copy", table.metadata_location)    print("rows in archive copy:", scan_arrow(same.load_table("archive.pageviews_copy")).num_rows)    # An object with another name does not see the namespace: the SQL catalog keeps tables apart by catalog name.    try:        open_catalog(wh, name="other").list_tables(NAMESPACE)    except Exception as exc:        print("other name:", safe_error(exc, wh))
輸出python register-iceberg-table.py
rows read through the second object: 1499
rows in the loaded object after another append: 1499
rows after a reload: 1999
rows in archive copy: 1999
other name: NoSuchNamespaceError: Namespace does not exist: wiki

第二個物件讀到 wiki.pageviews_hourly 的 1499 列資料,也就是第 1 章所載入的三個小時。pyiceberg 會將每個資料表存放在你傳給 SqlCatalog 的目錄名稱之下。名稱相同的物件會找到相同的資料表。

目錄與倉儲資料夾是成對的。目錄保存中繼資料檔的位置,而這些位置位於 warehouse 屬性所指定的資料夾之下。若只有目錄檔案的副本而沒有倉儲資料夾,或只有資料夾而沒有檔案,得到的都會是指向不存在檔案的指標。請同時備份兩者,也請一併搬移。

每個行程都會開啟自己的目錄物件,彼此不共用狀態。在這裡,同一個行程中的兩個物件用來代表兩個行程。

已載入的資料表會保持載入當時的狀態。在第四個小時附加資料之前取得的物件,讀到的仍是 1499 列,而重新載入後讀到的是 1999 列。若行程在開始時載入資料表,到結束時才讀取,讀到的是開始時的狀態。它必須重新載入,才能看到期間完成的提交。

實用原則: 在程式碼各處都以同一個名稱開啟 SQL 目錄檔案;當自載入之後可能有其他寫入者提交變更時,請在讀取資料表之前先重新載入。SQLite 只用於同一時間一個寫入者的情況,要執行多個寫入者之前,請改用為並行寫入者設計的資料庫。

從中繼資料檔註冊資料表

最近一次變動於第 2026.11.7 版

register_table(identifier, metadata_location) 會為既有的中繼資料檔新增一個名稱。pyiceberg API 頁面將它列為從中繼資料註冊資料表的方式,並說明傳入 overwrite=True 會取代已存在的項目。本範例將資料表的中繼資料註冊為 archive.pageviews_copy,所在的命名空間則是先行建立的。這個封存名稱讀到的資料列與原始資料表相同,共 1999 列。兩個名稱指向同一份中繼資料,而且註冊過程不會寫入任何資料檔。

註冊的名稱是通往同一個資料表的第二條路徑,並不是第二個資料表。透過其中一個名稱提交的變更,就是兩個名稱共同的變更,因為兩者讀取的是同一份中繼資料。請將第二個名稱視為讀取路徑,而不要當成備份。

實用原則: 每個資料表只保留一個寫入名稱。只有在要進行之後會移除的讀取作業時,才將中繼資料檔註冊為第二個名稱;而且只有在確定要取代該項目時,才傳入 overwrite=True。

附加 DuckLake 目錄

最近一次變動於第 2026.11.7 版

DuckLake 的目錄是一個資料庫檔案,DuckDB 以 ATTACH 陳述式附加它,該陳述式以 ducklake: 開頭,並給出檔案的路徑。資料路徑是 DuckLake 寫入 Parquet 檔案的資料夾,它儲存在目錄中。DuckLake 連線頁面指出,只有在建立新的 DuckLake 時才需要指定資料儲存位置,之後該位置會從目錄資料庫載入。輔助函式 connect_ducklake 會在關閉下載的情況下,將 DuckLake 載入 DuckDB 工作階段;attach_ducklake 則針對某個資料夾下的目錄檔案執行 ATTACH。

下一個範例在全新的 DuckLake 目錄中建立 wiki.domains,將它分離,然後不指定資料路徑,再次附加該檔案。接著列出該檔案中 wiki 結構描述內的資料表。

attach-ducklake.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Attach a DuckLake catalog file, detach it, and attach it again from the file alone. The point rests on the'rows after re-attach' line, and the table list shows what the catalog holds, not what the data folder holds."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, attach_ducklake, connect_ducklake,                           create_ducklake_domains, new_warehouse, print_rows, sql_rows)with new_warehouse() as wh:    con = connect_ducklake(wh.con)    create_ducklake_domains(con, wh.root)                # inlining is off, so the rows become Parquet files    print("rows written:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])    # Detach, then attach with no DATA_PATH: the catalog file stores the data path.    con.execute(f"DETACH {DUCKLAKE_ALIAS}")    attach_ducklake(con, DUCKLAKE_ALIAS, wh.root)    print("tables in the catalog:")    print_rows(sql_rows(con, f"""SELECT schema_name, table_name FROM duckdb_tables()                                 WHERE database_name = '{DUCKLAKE_ALIAS}' AND schema_name = '{NAMESPACE}'"""))    print("rows after re-attach:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])
輸出python attach-ducklake.py
rows written: 4
tables in the catalog:
wiki	domains
rows after re-attach: 4

wiki.domains 寫入了 4 列,重新附加後讀回 4 列。資料表清單顯示 wiki 結構描述中有一個資料表,即 domains。第二次附加不需要資料路徑,因為檔案本身已記錄了它。這份清單來自目錄,而不是資料資料夾。目錄檔案保存資料表清單,資料資料夾保存實際的位元組。即使後者完好,一旦遺失前者,名稱也會隨之消失,如失敗情境一節所示。

同一個連線頁面指出,DuckLake 會將小型插入內嵌到目錄資料庫中,預設上限為 10 列。本章使用的輔助函式把內嵌上限設為 0,因此這些範例中的每次插入都會成為資料資料夾中的一個 Parquet 檔案,這項設定在第 1 章中有說明。若沒有這項設定,小型資料表會存放在目錄檔案內,而資料資料夾的副本將不包含其資料列。這是目錄檔案需要單獨備份的原因之一。

實用原則: 備份 DuckLake 目錄檔案時,要連同資料資料夾一起備份,並在沒有任何工作階段附加該檔案時再複製。建立目錄時要指定資料路徑,之後只用目錄檔案本身來附加。

以路徑尋找資料表,不使用目錄服務

最近一次變動於第 2026.11.7 版

本書中的 Delta Lake 資料表就是一個資料夾。它沒有目錄服務(catalog),本書的環境設定中,除了路徑之外,沒有任何東西為它命名。deltalake 套件以 DeltaTable(path) 開啟該資料夾,每一次讀取都經由這個路徑進行。下一個範例中的三次附加寫入,分別是版本 0、1 和 2。

open-delta-by-path.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Open a Delta Lake table by its path, with no catalog, and read its first version and its current one. The pointrests on the 'rows at that version' and 'rows at version 0' lines, and the missing-path line shows the error."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_deltawith new_warehouse() as wh:    path = str(wh.root / "delta" / "pageviews_hourly")    for hour in range(3):        write_deltalake(path, read_cut_hour(hour), mode="append")   # each append is one version, counted from 0    table = DeltaTable(path)    print("delta version:", table.version())    print("rows at that version:", read_delta(path).num_rows)    print("rows at version 0:", read_delta(path, version=0).num_rows)    # The path is the only name a Delta table has here: a wrong path is a missing table.    try:        DeltaTable(str(wh.root / "delta" / "pageviews_typo"))           # a path never written, so no log to open        print("missing path: opened")    except Exception as exc:        print("missing path:", type(exc).__name__)
輸出python open-delta-by-path.py
delta version: 2
rows at that version: 1499
rows at version 0: 499
missing path: TableNotFoundError

資料表目前的版本是 2,讀出 1499 列資料。版本 0 有 499 列,也就是僅包含第一個小時的資料。這裡的資料列是透過 read_delta 讀取,它會傳回 Arrow 資料表。本章末尾的決策說明了本書為何以這種方式讀取 Delta 資料表。

路徑就是完整的名稱,因此路徑打錯,就等於資料表不存在。範例開啟了一個不存在的資料夾,DeltaTable 因而引發 TableNotFoundError。錯誤訊息會指出它嘗試開啟的路徑,但這要等到錯誤的路徑已經被使用之後才會發生,所以檢查應放在建立路徑的程式碼中。

對於由一個作業寫入、少數作業讀取的資料表,路徑是個好名稱。它不需要任何服務,也不需要任何設定。不過它也有代價。路徑並不會說明資料表位於哪個命名空間,所以兩個資料夾名稱相同、位置不同的資料表,在讀者眼中看起來一模一樣。想依名稱尋找資料表的引擎,也沒有任何可供查詢的依據。本書中的 Delta 資料表規模小且位於本機,路徑已經足夠。若是由多個引擎讀取的共用資料湖,其 Delta Lake 資料表就需要目錄服務,而本書不教授這部分。

實用原則: 將每個 Delta 資料表的路徑放在程式碼會讀取的單一位置,例如設定值,並在作業開始時開啟資料表一次,以確認路徑無誤。不存在的路徑是錯誤,而不是空的資料表。

跨兩個目錄聯結資料表

最近一次變動於第 2026.11.7 版

DuckDB 可以在同一個陳述式中,查詢由函式庫交給它的 Arrow 資料表,以及已附加到同一個工作階段的 DuckLake 資料表。Iceberg 資料表透過 scan_arrow 以 Arrow 資料表的形式離開 pyiceberg。DuckDB 會以一個名稱註冊該資料表,而聯結則透過已附加的目錄讀取 wiki.domains。本書不會為此載入 DuckDB 的 iceberg 擴充套件,因此 Iceberg 這一側就只是 Arrow 資料表,沒有其他東西。

join-pageviews-and-domains.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Join an Iceberg table, read through Arrow, with a DuckLake table in one DuckDB statement. The point rests on the'rows with no language' line, and the top-three block shows which rows the join returns first."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_iceberg_table,                           create_ducklake_domains, new_warehouse, print_rows, read_cut_hour,                           scan_arrow, sql_rows)with new_warehouse() as wh:    table = create_iceberg_table(wh)    for hour in range(3):                                # hours 0, 1 and 2 of the cut        table.append(read_cut_hour(hour))    con = connect_ducklake(wh.con)    create_ducklake_domains(con, wh.root)    pageviews = scan_arrow(table)                        # read now: the join sees the table as it is at this line    # sql_rows registers pageviews under that keyword name, so the SQL can refer to it as pageviews    joined = f"FROM pageviews p JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code"    print("joined rows:", sql_rows(con, f"SELECT count(*) {joined}", pageviews=pageviews)[0][0])    # the left join keeps every pageview, and this condition counts the ones that found no domain row    print("rows with no language:", sql_rows(con, f"""SELECT count(*) FROM pageviews p        LEFT JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code        WHERE d.domain_code IS NULL""", pageviews=pageviews)[0][0])    print("top three by views:")    print_rows(sql_rows(con, f"""SELECT p.domain_code, d.language, p.page_title, p.views {joined}        ORDER BY p.views DESC, p.domain_code, p.page_title, p.hour_utc LIMIT 3""", pageviews=pageviews, keep_order=True),        keep_order=True)
輸出python join-pageviews-and-domains.py
joined rows: 1499
rows with no language: 0
top three by views:
en	English	Main_Page	64859
en	English	Main_Page	64564
en	English	Main_Page	61107

頁面瀏覽紀錄中的每個網域代碼,都存在於這個有 4 列的維度資料表中。這個聯結為 1499 列頁面瀏覽紀錄對應到語言,並留下 0 列沒有對應語言。瀏覽次數最高的前三名是同一個頁面,也就是英文網域上的 Main_Page。

聯結鍵是 domain_code,兩側都是字串。如果聯結鍵在大小寫或尾端空白上不一致,就不會有任何比對結果:聯結後的列數會降為 0,而沒有語言的列數會等於資料表的總列數。在採信聯結結果之前,請在同一個工作階段中檢查兩側的鍵。

這個查詢之所以可行,是因為兩側在同一個 DuckDB 工作階段中會合。這並不會讓兩個資料表合而為一。各自保有自己的提交紀錄,而 Arrow 資料表是 scan_arrow 執行當下 Iceberg 資料表的快照。對於另一個寫入者正在變更的資料表進行聯結時,讀到的是當下那一刻的任何狀態。

對於像這樣的查找,我們建議使用跨目錄聯結:小型維度資料表留在自己的目錄中,由針對大型資料表的查詢來讀取。當一個資料表出現在幾乎每一個讀取另一個資料表的查詢中時,就把它複製到那些查詢所使用的目錄。第 9 章會在不同格式之間複製資料表,並檢查每一份複本,而在你搬移任何資料表之前,都應該先做這項檢查。

**實用原則:**只有在以 Arrow 形式讀取的那一側能放進記憶體時,才在同一個工作階段中跨目錄聯結。請在讀取之前選定它的狀態,並計算找不到對應的列數,這個數字應該為零。

此部分尚未翻譯,因此以英文呈現。

What goes wrong in production

最近一次變動於第 2026.11.10 版

The symptoms are usually small: a count that stops moving, a namespace that is missing, or a read error on a table that was read before. Each case here starts from one of them.

Only the last failure below has no example.

The wrong catalog name. The last line of register-iceberg-table opens the same file under the name other. Listing the namespace then fails with NoSuchNamespaceError: Namespace does not exist: wiki. The table is still in the file. The SQL catalog scopes its tables by catalog name, so the second name sees an empty catalog. The message names the namespace, not the name, so the error looks like a missing schema. A job that builds its catalog name from configuration can fail this way after a small edit. You notice it at the first read, not at the write, so log the catalog name at the start of the job.

The stale pointer. A process that loads a table and reads it much later reads the state from when it loaded. register-iceberg-table showed 1499 rows in the loaded object, where a reload shows 1999. Nothing fails. The job runs and reports fewer rows than the table holds. You notice it when two jobs disagree about a count, so keep the load next to the read.

The catalog file replaced by an empty one. The next example attaches a fresh, empty catalog file to the data folder of a live catalog, then runs ducklake_delete_orphaned_files with cleanup_all => true. The DuckLake cleanup page shows cleanup_all deleting all orphaned files, and dry_run listing them instead. It defines an orphan as a file that the catalog you run it against does not track. A fresh catalog tracks nothing, so every Parquet file in the folder is an orphan to it.

ducklake-orphan-cleanup-hazard.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Run cleanup_all against a fresh, empty DuckLake catalog that shares a data folder with a live one. The point restson the 'parquet files after cleanup_all' line and the 'reading the live catalog' line."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_ducklake_domains,                           new_warehouse, sql_rows)# One statement, run twice: first with dry_run => true, then for real. {dry} holds the dry-run argument or nothing.CLEANUP = "CALL ducklake_delete_orphaned_files('fresh', cleanup_all => true{dry})"def parquet_count(root):    # the data folder that attach_ducklake gives the catalog with the live alias; rglob searches it at any depth    return len(list((root / f"{DUCKLAKE_ALIAS}_data").rglob("*.parquet")))with new_warehouse() as wh:    con = connect_ducklake(wh.con)    create_ducklake_domains(con, wh.root)    print("parquet files, live catalog:", parquet_count(wh.root))    # A replacement catalog: a new, empty file that points at the same data folder.    con.execute(f"DETACH {DUCKLAKE_ALIAS}")    # Attached by hand: attach_ducklake would give fresh its own data folder, not the live one.    con.execute(f"ATTACH 'ducklake:{wh.root}/fresh.ducklake' AS fresh (DATA_PATH '{wh.root}/{DUCKLAKE_ALIAS}_data/')")    print("files the dry run lists:", len(sql_rows(con, CLEANUP.format(dry=", dry_run => true"))))    con.execute(CLEANUP.format(dry=""))    print("parquet files after cleanup_all:", parquet_count(wh.root))    # The live catalog still names the table, and its data files are gone.    con.execute(f"ATTACH 'ducklake:{wh.root}/{DUCKLAKE_ALIAS}.ducklake' AS live")    print("count through the live catalog:", sql_rows(con, f"SELECT count(*) FROM live.{NAMESPACE}.domains")[0][0])    try:        print("reading the live catalog:", len(sql_rows(con, f"SELECT domain_code, language FROM live.{NAMESPACE}.domains")))    except Exception as exc:        print("reading the live catalog:", type(exc).__name__)
輸出python ducklake-orphan-cleanup-hazard.py
parquet files, live catalog: 1
files the dry run lists: 1
parquet files after cleanup_all: 0
count through the live catalog: 4
reading the live catalog: IOException

A fresh catalog is enough to delete the live data. Before the cleanup, the live catalog's data is in 1 Parquet file. The dry run with cleanup_all lists 1 file, which the real run deletes, and afterwards the folder holds 0 Parquet files.

A count check passes here, and that is the trap: it does not show missing files. The live catalog still names the table, and it answers count(*) with 4, from the catalog's statistics. Reading its columns fails with IOException.

The safe order begins with what the example skipped. Back up the catalog file first. Run the cleanup with dry_run => true against the catalog that owns the data folder, and read the list. Run it for real only when every listed file is one you know is orphaned. Never run cleanup_all => true against a catalog you have not confirmed.

Two writers on one SQLite catalog. The pyiceberg documentation says SQLite is not built for concurrency. This chapter does not show what two writers do to the SQL catalog, so the book does not claim that they are safe. The stale-pointer example is the nearest case it does show: an object loaded before a commit reads the older state, and no error is raised. A writer that holds an old object does not write against that old state. At the pinned version of pyiceberg, an append through such an object is retried against the new metadata and commits on top of the newer state. The book makes no claim for other operations, or for two processes on one SQLite catalog. The reload rule in the SQL catalog section applies to reads.

Working rule: Run an orphan cleanup with dry_run => true first, against the catalog that owns the data folder, and read the list before any real run. If the catalog file is missing or empty, restore it before you run anything that deletes files.

本章做出的決定

最近一次變動於第 2026.11.7 版
  • Iceberg 登錄於以 SQLite 為後端的 pyiceberg SQL 目錄(catalog),並使用本機倉儲(warehouse)。 本書只有一個目錄名稱 local,所有範例都使用它。pyiceberg 文件說明 SQLite 適用於開發環境,而本書的範例都是開發範例。
  • Iceberg 資料表以 Arrow 資料表的形式交給 DuckDB。 本書不使用 DuckDB 的 iceberg 擴充套件,因此範例透過 scan_arrow 讀取 Iceberg 資料。
  • Delta Lake 資料表以路徑尋找,本書不教授任何 Delta 目錄。 每個 Delta 範例都是開啟一個資料夾,資料夾不存在即為錯誤。
  • Delta 資料表僅透過 QueryBuilder 讀取。 這是本書建置過程中的量測結果,並非第一手資料來源。在固定的版本下,其他 Arrow 轉換方法在 20 次執行中約有 17 次於結束時使程序中止。QueryBuilder 路徑在 24 次執行中一次也沒有中止,其中包括讀取較早版本的情況。
  • DuckLake 由 connect_ducklake 載入,並關閉下載功能。 每個範例都在固定版本的 DuckDB 上離線執行。
  • 清理的風險範例在暫存資料夾中執行,且只印出數量。 本書展示失敗的情況,使安全步驟的順序一目了然。本書不印出檔案名稱,因為檔名在每次執行時都會改變。
  • 每個範例只印出數量與附有標籤的值, 原因見第 1 章:如此一來,輸出在每次執行、每部機器上都會相同。
  • REST 目錄沒有可執行的範例。 它們需要網路,因此本章依據其頁面說明該協定,不對任何產品作出主張。

本章,於本版次中

版次 2026.11.10範例於 2026年11 月 20 通過測試本章 5 個範例 個範例中有 5 個通過

譯自英文書,版次 2026.11.10。

引用本節

格式

各種格式皆引用英文原書,本譯本即依循該原書。

每種格式都會標示本版。其連結會開啟目前版次,節標題會說明該節內文最後一次變動的時間。存取日期與擷取日期即為你開啟此頁的當日。

本頁內容

第 8 章,共 10 章: 在目錄中註冊資料表,並從 DuckDB 查詢

  1. 目錄存放什麼
  2. 在 SQL 型目錄中註冊資料表
  3. 從中繼資料檔註冊資料表
  4. 附加 DuckLake 目錄
  5. 以路徑尋找資料表,不使用目錄服務
  6. 跨兩個目錄聯結資料表
  7. What goes wrong in production
  8. 本章做出的決定

返回頂端所有章節