讀取資料表在較早快照時的狀態

閱讀約需 40 分鐘 分鐘,7 節 中共有 3 個範例。

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

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

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

本章教你讀取資料表在較早一次提交之後的狀態,三種格式都會涵蓋:列出其提交、依各格式使用的編號讀取其中一次提交,並在不同格式之間比較這些編號而不致混淆。

假設 wiki.pageviews_hourly 的儀表板總計(依小時加總 views)在第三個小時的資料寫入後出現變動,而負責人提出兩個問題:該次提交之前的總計是多少?變動的是資料表,還是只有查詢?要回答這兩個問題,需要資料表的歷史紀錄,以及讀取資料表舊狀態的方法。這個資料表有五個欄位:hour_utc、domain_code、page_title、views 與 response_bytes。本章的每個範例都會建立自己的資料表副本,做法與第 1 章相同:建立資料表,並以三次提交附加 00、01 與 02 時的資料。00 時有 499 列,其餘兩個小時各有 500 列。

每次提交都是一個快照

最近一次變動於第 2026.11.10 版

第 1 章把這三個小時的資料寫成三次提交。每次提交都會留下一個快照,而你之後讀取的就是這個快照。

一次提交以單一的原子步驟變更資料表的中繼資料,因此讀取端看到的不是提交之前的資料表,就是提交之後的資料表,不會看到介於兩者之間的狀態。在 Apache Iceberg 中,每次提交都會建立一個快照。Iceberg 規格將快照定義為「資料表在某個時間點的狀態」,用來存取資料表中完整的資料檔案集合,並將每次變更描述為中繼資料檔案的一次原子替換。快照具有唯一的 ID、建立時間與摘要。快照的摘要有一個必要欄位 operation,其值為 append、replace、overwrite 或 delete 其中之一。append 表示新增了資料檔案,且沒有移除任何檔案。之後的提交會新增一個快照,並保留先前的快照不動,這正是讓儀表板負責人能夠詢問已不是最新狀態的原因。

在進行任何掃描之前,先讀取歷史紀錄:本範例依序列出三次提交,每次都附上其操作與新增的列數,先列出 Iceberg 的結果,再列出 Delta Lake 的結果。

snapshot-history.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Commit three hours to an Iceberg table and a Delta Lake table, then list each commit with its operation and rows added.The prose's point that all three Iceberg commits are appends rests on the operation lines for the snapshots."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import ICEBERG_ID, PAGEVIEWS_SCHEMA, new_warehouse, read_cut_hour, snapshot_labelsdef main():    with new_warehouse() as wh:        table = wh.catalog.create_table(ICEBERG_ID, schema=PAGEVIEWS_SCHEMA)        delta_path = str(wh.root / "delta" / "pageviews_hourly")        for hour in range(3):                       # hours 00, 01 and 02: one commit to each table per hour            batch = read_cut_hour(hour)            table.append(batch)            write_deltalake(delta_path, batch, mode="append")        # sequence_number counts commits, so sorting by it puts the labels in commit order.        snapshots = sorted(table.snapshots(), key=lambda snapshot: snapshot.sequence_number)        labels = snapshot_labels([snapshot.snapshot_id for snapshot in snapshots])        for snapshot in snapshots:            label = labels[snapshot.snapshot_id]            operation = snapshot.summary.operation.value            print(f"{label} operation: {operation}")            # added-records counts only this commit's rows, not the table's running total.            print(f"{label} rows added: {snapshot.summary['added-records']}")        # Sorted by version, so the lines follow Delta's own numbering whatever order history returns.        history = sorted(DeltaTable(delta_path).history(), key=lambda entry: entry["version"])        for entry in history:            rows = entry["operationMetrics"]["num_added_rows"]      # Delta's count of the rows this WRITE added            print(f"version {entry['version']} operation: {entry['operation']}")            print(f"version {entry['version']} rows added: {rows}")if __name__ == "__main__":    main()
輸出python snapshot-history.py
snapshot 1 operation: append
snapshot 1 rows added: 499
snapshot 2 operation: append
snapshot 2 rows added: 500
snapshot 3 operation: append
snapshot 3 rows added: 500
version 0 operation: WRITE
version 0 rows added: 499
version 1 operation: WRITE
version 1 rows added: 500
version 2 operation: WRITE
version 2 rows added: 500

三次提交都使用 append,因此沒有任何一次改寫或移除檔案。第 00 小時新增了 499 列,比其他兩次少一列,原因是資料裁切時從中去掉了一列,資料 README對此有所說明。第 01 與第 02 小時各新增 500 列。負責人的問題從這裡開始:資料表有三個狀態可供選擇,而歷史紀錄指明了這三個狀態。

pyiceberg 為每個快照提供一個長整數 ID。我們不印出這些 ID,而是由 snapshot_labels 依提交順序將它們對應到「snapshot 1」、「snapshot 2」與「snapshot 3」這些標籤,輸出時只印出標籤。

同樣的三個小時資料,也透過 write_deltalake 寫入一個 Delta Lake 資料表,每小時寫入一次。Delta Lake 將每次提交稱為一個版本(version),其歷史紀錄會列出每個版本的操作與寫入的列數。Delta 的版本從 0 開始編號,因此第一次寫入是版本 0。本書印出 Delta 自己的編號,所以範例依版本排序歷史紀錄,並印出「version 0」、「version 1」與「version 2」。每次 Delta 寫入都是 WRITE 操作,新增的列數與對應的 Iceberg 快照相同:版本 0 為 499 列,其後為 500 與 500。

歷史紀錄回答了負責人問題的前半部分:它說明是哪一次提交變更了資料表,以及該次提交新增了多少列。append 只會新增列,因此不可能改變資料表中既有小時的總數。如果某個小時的總數有變動,歷史紀錄中必定會指出某個 overwrite、delete 或 replace 操作是原因,接著再讀取它前後兩側的快照。歷史紀錄不會說明查詢做了什麼,而問題的那個部分需要下一節的讀取操作。

**實用原則:**在讀取或變更資料表之前,先以你所用的格式列出其歷史紀錄,並將該清單作為提交編號的唯一來源。清單依提交順序排序,Iceberg 快照在印出前以 snapshot_labels 加上標籤,Delta 版本則照 Delta 自己的編號印出。讀取每次提交時一併看它的操作。append 只會新增檔案,因此不可能移除列,而 overwrite 或 delete 則可能移除。

快照所指向的內容

最近一次變動於第 2026.11.10 版

快照本身不存放資料列,它指向存放資料列的檔案。在格式版本 2 與 3 中,快照會記錄一份 manifest list,快照的檔案就是由此找到。前一節的定義讓快照成為通往完整資料檔案集合的入口,因此讀取端從快照出發,再循著它找到檔案。

這使快照成為一組指標,而這一點對後續每一節都有影響。快照只有在它所指名的檔案仍然存在時才能讀取。因此時間旅行並不是備份。它只能讀取資料表仍保留的檔案,而資料表只在某個快照指名某個檔案時才會保留該檔案。第 7 章會移除舊快照,以及只有這些快照指名的檔案,這會使人無法再時間旅行到那些狀態。

提交的操作類型顯示了哪些共用是可能的。規格將 append 定義為「只新增了資料檔案,且沒有移除任何檔案」的操作。因此快照 3 再次指名了 00 時的檔案,因為第三次提交並未重寫它們。多個快照可以指名同一個檔案,一次提交的成本只有它所寫入的檔案,加上指向這些檔案的指標。

pyiceberg 中的快照所列出的資料列數,展示了這些指標的運作。快照 2 讀回 999 列,也就是 00 時的 499 列加上 01 時的 500 列,而沒有 02 時的任何資料。快照 3 則讀到全部三個小時的資料。每個快照讀到的,是到當時為止各次提交已使其可見的資料列,不多也不少。兩個列數之間的差距,就是第三次提交所新增的資料列,共 500 列,所以歷史記錄與讀取結果是一致的。

**實用原則:**只有在舊快照的檔案仍然存在時,才把它視為可讀取。移除檔案之前,先決定要保留哪些快照,並先讓其他快照過期。若針對舊快照的查詢在清理之後失敗,原因就是檔案遺失。解決方法是從資料表的副本中找回該檔案,而不是改讀另一個快照來代替。

讀取較早的快照

讀取較早的快照,指的是在掃描資料表時指定該快照。每種格式都有各自指定快照的方式。Iceberg 使用快照 ID。DuckLake 在 AT (VERSION => n) 中使用快照編號。Delta Lake 使用版本號。這三種編號所計算的對象並不相同。

擁有者的第一個問題是:第三個小時的資料寫入之前,總數是多少。答案是第二次提交之後的狀態,也就是快照 2。

pyiceberg 中的快照

最近一次變動於第 2026.11.7 版

在 pyiceberg 0.12.0 中,scan(snapshot_id=...) 會讀取該快照當時的資料表狀態,而未指定快照 ID 的掃描則讀取目前的快照。以 ID 進行的兩次掃描,可以從資料表自身的歷史回答擁有者的第一個問題;此範例也會讀取目前的資料表,並與快照 3 比較。

read-as-of-snapshot.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Read an Iceberg table as of snapshot 2 and snapshot 3, by ID, then compare the current table with snapshot 3.The prose's answer to the owner's first question rests on the snapshot 2 views line, and the failed read on the last line."""from lib.lakehouse import (    ICEBERG_ID, PAGEVIEWS_SCHEMA, new_warehouse, read_cut_hour, safe_error, scan_arrow, snapshot_labels, sql_rows,)def main():    with new_warehouse() as wh:        table = wh.catalog.create_table(ICEBERG_ID, schema=PAGEVIEWS_SCHEMA)        for hour in range(3):            table.append(read_cut_hour(hour))        snapshots = sorted(table.snapshots(), key=lambda snapshot: snapshot.sequence_number)        ids = [snapshot.snapshot_id for snapshot in snapshots]        labels = snapshot_labels(ids)        # ids[1] is snapshot 2 and ids[2] is snapshot 3: the list is in commit order, counted from 0.        for snapshot_id in (ids[1], ids[2]):            arrow = scan_arrow(table, snapshot_id=snapshot_id)            # The scan is registered in DuckDB as t, so the SQL can count and sum its rows.            rows, views = sql_rows(wh.con, "SELECT count(*), sum(views) FROM t", t=arrow)[0]            print(f"{labels[snapshot_id]} rows: {rows}")            print(f"{labels[snapshot_id]} views: {views}")        current = scan_arrow(table)                  # no snapshot_id, so this reads the current snapshot        last = scan_arrow(table, snapshot_id=ids[2])        print(f"current rows: {current.num_rows}")        # equals compares every row and column, in order; scan_arrow sorts both tables by every column, so row order cannot differ.        assert current.equals(last)        try:            scan_arrow(table, snapshot_id=2)         # 2 is the label's number, not an ID, so this fails on purpose        except Exception as exc:            print(f"read by label: {safe_error(exc, wh)}")if __name__ == "__main__":    main()
輸出python read-as-of-snapshot.py
snapshot 2 rows: 999
snapshot 2 views: 580963
snapshot 3 rows: 1499
snapshot 3 views: 899451
current rows: 1499
read by label: ValueError: Snapshot not found: 2

快照 2 回答了擁有者的第一個問題。在第三次提交之前,資料表的瀏覽總數為 580963;之後的快照 3 則為 899451。不指定 ID 讀取資料表,得到的資料列與快照 3 相同,而且這項檢查比較的是資料列本身,而不只是列數。

views 欄位回答了擁有者的第二個問題。快照 3 的瀏覽數比快照 2 多,差額就是 02 時新增的瀏覽數。總數改變,是因為第三次提交新增了資料列,而不是因為儀表板的查詢改變了。對同一個資料表讀取兩次,就能在不更動查詢的情況下說明這一點。

心中想著「快照 2」這個標籤的讀者,可能會把數字 2 當成 ID 傳入。這個呼叫會失敗,而這樣的失敗是安全的結果:

ValueError: Snapshot not found: 2

錯誤訊息指出它收到的數字,而該數字並不是快照 ID,資料表也沒有任何變動。讀者便知道應該去查詢 ID。範例本身是在 table.snapshots() 中查出每個 ID,絕不從計數推算 ID。標籤是為了行文而設,ID 則是為了掃描而用。

實用原則: 從 table.snapshots() 取得快照 ID,並傳入你查到的 ID,而不是標籤的數字。在印出任何內容之前,先依提交順序將 ID 對應到標籤。當問題是某次提交之後的狀態時,先在歷史中找到該次提交,再讀取它所建立的快照。

以編號讀取各格式中的提交

最近一次變動於第 2026.11.10 版

Delta Lake 以 DeltaTable(path, version=n) 讀取較早的版本。版本是該提交在資料表歷史中的位置,從 0 起算,因此版本 0 是第一次寫入。輔助函式 read_delta 接收路徑與選用的版本,並以排序後的 Arrow 資料表回傳資料列。本書中所有 Delta 的讀取都經由 deltalake 的 QueryBuilder,輔助函式會替你呼叫它。理由見決策節。

DuckLake 對目錄(catalog)的每一次變更都保留一個快照,變更包括建立結構描述(schema)與建立資料表。DuckLake 的快照同樣從 0 起算,所以新目錄中的第一次插入並不是編號 1。DuckLake 時間旅行頁面展示了讀取快照的子句 SELECT * FROM tbl AT (VERSION => 3);,並說明要查詢的快照可以由時間戳記指定,或「明確使用快照識別碼」指定。本書使用識別碼。你應從 ducklake_snapshots 讀取該編號,而不是自行以插入次數推算。

三版本範例讓編號彼此分歧,而資料列數卻相符:它把相同的三個小時寫入 Delta 資料表與 DuckLake 資料表,每種格式每小時各一次提交。它以編號讀回每一次提交,印出兩邊的資料列數,計算第一次插入之前的 DuckLake 快照數,並示範一種失敗情形。

three-version-numbers.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 通過
"""Commit the same three hours to Delta Lake and DuckLake, then read each commit back by its own number.The prose's point that each hour gives the same row count in both formats rests on the paired row-count lines."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, TABLE, attach_ducklake, connect_ducklake, new_warehouse,                           read_cut_hour, read_delta, safe_error, snapshot_labels, sql_rows)LAKE_TABLE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"CATALOG_SNAPSHOTS = f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}')"# Fetches snapshot_time, which turns into Python values through pytz; the pins do not install pytz, so this fails on purpose.TIME_COLUMN = f"SELECT snapshot_time FROM ducklake_snapshots('{DUCKLAKE_ALIAS}')"def main():    with new_warehouse() as wh:        delta_path = str(wh.root / "delta" / TABLE)        connect_ducklake(wh.con)        attach_ducklake(wh.con, DUCKLAKE_ALIAS, wh.root)        wh.con.execute(f"CREATE SCHEMA {DUCKLAKE_ALIAS}.{NAMESPACE}")        # A zero-row slice of hour 00: it gives the table its columns and types, and no rows.        sql_rows(wh.con, f"CREATE TABLE {LAKE_TABLE} AS SELECT * FROM empty", empty=read_cut_hour(0).slice(0, 0))        for hour in range(3):                        # hours 00, 01 and 02, one commit to each table per hour            batch = read_cut_hour(hour)            write_deltalake(delta_path, batch, mode="append")            sql_rows(wh.con, f"INSERT INTO {LAKE_TABLE} SELECT * FROM batch", batch=batch)        # Keeps only the snapshots that inserted rows, so the schema and table creations are left out.        inserts = sorted(row[0] for row in sql_rows(wh.con, CATALOG_SNAPSHOTS + " WHERE map_contains(changes, 'tables_inserted_into')"))        # Snapshot IDs count up with each change, so these are the snapshots made before the first insert.        before = sql_rows(wh.con, CATALOG_SNAPSHOTS + f" WHERE snapshot_id < {inserts[0]}")        print(f"snapshots before the first insert: {len(before)}")        # Labels count every DuckLake snapshot from 1, setup snapshots included, not DuckLake's own numbers.        lake_labels = snapshot_labels(sorted(row[0] for row in sql_rows(wh.con, CATALOG_SNAPSHOTS)))        delta_versions = list(range(DeltaTable(delta_path).version() + 1))     # Delta versions run from 0 to the latest        # zip pairs each hour's Delta version with its DuckLake insert, in order; strict fails if the counts differ.        for hour, (delta_version, snapshot) in enumerate(zip(delta_versions, inserts, strict=True)):            # DuckLake reads by the snapshot ID from ducklake_snapshots, never by counting the inserts.            lake = sql_rows(wh.con, f"SELECT count(*) FROM {LAKE_TABLE} AT (VERSION => {snapshot})")[0][0]            rows = len(read_delta(delta_path, version=delta_version))     # read_delta goes through QueryBuilder, because to_pyarrow_table() aborted at exit in some test runs at these pins.            print(f"after hour {hour:02d}, Delta version {delta_version} rows: {rows}")            print(f"after hour {hour:02d}, DuckLake {lake_labels[snapshot]} rows: {lake}")        try:            wh.con.execute(TIME_COLUMN).fetchall()        except Exception as exc:            print(f"select time: {safe_error(exc, wh)}")if __name__ == "__main__":    main()
輸出python three-version-numbers.py
snapshots before the first insert: 3
after hour 00, Delta version 0 rows: 499
after hour 00, DuckLake snapshot 4 rows: 499
after hour 01, Delta version 1 rows: 999
after hour 01, DuckLake snapshot 5 rows: 999
after hour 02, Delta version 2 rows: 1499
after hour 02, DuckLake snapshot 6 rows: 1499
select time: InvalidInputException: Invalid Input Error: Required module 'pytz' failed to import, due to the following Python exception:
ModuleNotFoundError: No module named 'pytz'

第一次插入是「快照 4」而不是「快照 1」,因為在它之前 DuckLake 目錄已經有 3 個快照:DuckLake 在附加(attach)時建立的預設結構描述、wiki 結構描述,以及該資料表。本書以 1 為起點標記 DuckLake 的快照,並把初始設定計入,所以「快照 4」就是 DuckLake 自己的編號 3 加 1。若讀者從 1 開始計算插入次數,就會得到錯誤的標記。

每個小時之後,兩種格式持有的資料列數相同,儘管它們對提交的編號方式不同。由於兩種格式沒有共用的編號,小時才是把它們對齊的鍵。在小時 02 之後,也就是完整的資料表,Delta 版本 2 有 1499 列,DuckLake 快照 6 有 1499 列,較早的小時也以同樣方式相符。

下表並列這三種編號。

格式 指稱提交的編號 計入哪些變更 讀取方式
Iceberg 快照 ID,長整數 資料表的每一次提交 scan(snapshot_id=...)
Delta Lake 版本,從 0 起算 資料表的每一次提交 DeltaTable(path, version=n)
DuckLake 快照編號,從 0 起算(本書的標記高一號) 目錄的每一次變更,包括建立結構描述與資料表 AT (VERSION => n)

**實用原則:**以每次提交所載入的小時來比較各格式,切勿以原始編號比較。印出 Iceberg 與 DuckLake 的快照時附上其標記,印出 Delta 版本時採用 Delta 自己的編號,並把資料列數與它們綁定。Delta 只經由 read_delta 讀取,DuckLake 只使用來自 ducklake_snapshots 的編號。若某一種格式的資料表收到了另一種格式沒有的提交,標記就不再對齊,此時各格式自己的歷史便成為唯一可靠的紀錄。

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

What goes wrong in production

最近一次變動於第 2026.11.7 版

The failures in this chapter are the ones a reader is likely to meet first. The first two appear in this chapter's examples. The third and fourth are argued from the documentation and the book's rules, and the fifth and sixth lean on chapter 1 and chapter 7. The first is the number that is not an ID. A failed scan is a safe failure, because the error says what was wrong. Worse failures come from reading a number that is valid in one format and means something else in another, or from a query that runs and returns something unexpected. The read-as-of-snapshot example shows the first kind: the ID guess fails loudly, and the error text names the value that was passed.

Fetching a time column fails for a different reason, a missing module. The three-version example includes a select of snapshot_time from ducklake_snapshots, and the call fails:

InvalidInputException: Invalid Input Error: Required module 'pytz' failed to import, due to the following Python exception:

The message says the pytz module is missing. The pinned environment does not install it. DuckDB's Python client needs pytz to turn a TIMESTAMPTZ column such as snapshot_time into Python values. The three-version example avoids the problem by selecting only snapshot_id and filtering on changes, so it never fetches snapshot_time. To read the time anyway, cast it with snapshot_time::VARCHAR. Leave out the column or cast it; we would rather not add a package the book does not pin.

Reading by timestamp is the third trap. DuckLake accepts a timestamp in AT (TIMESTAMP => ...), and Iceberg snapshots have a creation time. A timestamp picks a state by the clock, and the clock is the time when each commit ran. In production that is a good way to ask for "the table as it was at nine in the morning". An example would have to take a clock time from the run, which changes on every run, so the book uses IDs and version numbers instead. Choose the timestamp form when you need a point in wall-clock time and you have a record of when each commit ran. Choose the number form when you need the same answer every time.

Numbers drift between formats. Two formats can hold the same table, and the same label can then name different states. The book's example commits the same hours in the same order, so the labels agree. A production table that receives a repair in one format and not the other will not agree. Even with identical histories, the raw numbers do not line up across formats, because DuckLake's snapshot numbers also count schema and table creation. A dashboard that reads "version 4" from both formats will show different totals, so compare commits by their labels. The check is to compare the row counts for the label in both formats before you trust either number. The three-version example does that.

A file count can also read low, because DuckLake may keep a small insert in the catalog instead of writing a Parquet file, under the default chapter 1 names. The example's first hourly batch alone holds 499 rows, far over that limit, so under that default each of its inserts is written as a file. A count of data files is only meaningful once you know the row limit.

The failure this chapter warns about most comes later, at a read after a cleanup. What a snapshot points to gives the reason: the error appears only when a reader asks for a snapshot whose files are gone. Nothing fails at the cleanup itself. Chapter 7 shows which files a cleanup removes.

Working rule: Read the error text before you change the query. It names the value, the module or the version that failed, and that is the fastest route to the fix. Compare each count in one format with the same label in the other format before you trust either one. Keep the snapshot your question needs readable until the question is answered, and expire only the snapshots that no question still needs. Record the label and the format's name with every number you report, so that a reader of the report can reproduce it.

本章的決定

最近一次變動於第 2026.11.7 版
  • 使用標籤,而非 ID。 輸出的各行使用「snapshot 2」這類標籤標示 Iceberg 與 DuckLake 的快照,標籤從 1 開始,涵蓋該格式記錄的每一個快照。對 DuckLake 而言,這包含三個設定用的快照,因此 DuckLake 自己的編號會少 1。Iceberg 的 ID 與 DuckLake 的快照編號都不會出現在輸出中。Delta 則印出它的版本號,版本號從 0 開始計算,也是讀者傳給 DeltaTable 的數字。讀者可以重新執行範例,逐行比對文字,而差異只會顯示資料或函式庫的變動,不會是隨機 ID 的變動。標籤依提交順序對應,因此即使函式庫以其他順序傳回歷史紀錄,標籤的意義也不會改變。
  • 使用 ID 與版本號,而非時間戳記。 以時間戳記讀取會取決於時鐘,以及各次提交執行的時間。我們改以 ID 或編號讀取,讓讀者無論何時執行範例,都能從同一次提交得到相同的資料列。需要實際時間的正式環境讀者,應使用時間戳記的形式,並自行記錄每次提交的執行時間。
  • Delta 僅透過 read_delta 讀取。 輔助函式透過 deltalake 的 QueryBuilder 讀取。在這些固定的版本下,to_pyarrow_table() 路徑在某些執行中會於結束時中止,如第 8 章所量測。我們修正讀取路徑,而不是繞過這個中止問題,因此沒有任何範例呼叫 os._exit 或隱藏結束狀態。
  • DuckLake 僅透過輔助函式使用。 每次 DuckLake 的執行都以 connect_ducklake 載入 DuckLake,並以 attach_ducklake 掛載。我們從不設定 allow_unsigned_extensions。本書的執行會在輔助函式依 SOURCE.toml 檢查兩個雜湊值之後,從儲存庫中隨附的檔案載入 DuckDB 官方簽署的 DuckLake 擴充套件,因此離線執行不需要下載。只有在讀者自己的機器上,且該隨附檔案不存在時,connect_ducklake 才會執行 INSTALL ducklake。
  • 對目錄的查詢保持精簡。 對 ducklake_snapshots 的查詢會明確指定欄位名稱,並省略 snapshot_time,因為該欄位需要一個固定版本並未安裝的模組。我們寧可明確指定所需的欄位,也不新增固定版本中沒有記錄的相依套件。
  • Delta 保留自己的編號。 Delta 印出它真實的版本號,從 0 開始計算。每個標籤只說明該提交在其自身資料表中的位置,絕不表示兩種格式持有相同的狀態。比對各標籤的資料列數,才能確認這一點。
  • 失敗只印出,不拋出。 有兩個範例以刻意失敗的呼叫作結,各自捕捉錯誤並印出。之所以呈現失敗,是因為讀者會遇到它,而完整印出錯誤文字,是為了讓讀者能與自己的輸出比對。
  • 先讀歷史,再讀狀態。 程式碼先列出各格式的提交,之後才依編號讀取某次提交。本章的讀者在任何掃描之前,就會先得到每次提交的操作與資料列數,因此看起來不對的筆數,可以對照產生它的那次提交來檢查。

本章,於本版次中

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

譯自英文書,版次 2026.11.10。

引用本節

格式

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

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

本頁內容

第 2 章,共 10 章: 讀取資料表在較早快照時的狀態

  1. 每次提交都是一個快照
  2. 快照所指向的內容
  3. 讀取較早的快照
  4. pyiceberg 中的快照
  5. 以編號讀取各格式中的提交
  6. What goes wrong in production
  7. 本章的決定

返回頂端所有章節