以前のスナップショットの時点のテーブルを読む

読了まで約36 分分、7 節 節の 3 例 例。

第2026.11.10版 2026年11月20日時点で例が通過 39 例中 39 例が合格 変更点

AIによる翻訳。英語版は人による検証済みである。 当社の書籍の作り方

英語版の書籍(版2026.11.10)から翻訳した。 原文を読む

この章では、以前のコミットの後のテーブルを、三つのフォーマットのそれぞれで読む方法を学ぶ。コミットを一覧し、各フォーマットが使う番号で一つを読み、それらの番号をフォーマット間で取り違えずに比較する。

wiki.pageviews_hourly のダッシュボードの合計は、views を時間ごとに合計したものであるが、この値が3時間目のデータの取り込み後に変化し、その担当者が二つの問いを立てたとする。そのコミットの前の合計はいくらだったか。また、変化したのはテーブルか、それともクエリだけか。これらに答えるには、テーブルの履歴と、テーブルの過去の状態を読む方法が必要である。テーブルには hour_utc、domain_code、page_title、views、response_bytes の五つの列がある。この章の各例は、第1章 と同様に、それぞれテーブルの独自のコピーを作る。テーブルを作成し、00時、01時、02時のデータを三つのコミットとして追加する。00時の行数は 499 であり、残りの2時間の行数はそれぞれ 500 である。

すべてのコミットがスナップショットになる

最終変更:版2026.11.10

第1章では、3時間分のデータを3回のコミットとして書き込む。各コミットはスナップショットを残し、後からデータを読むときに参照するのはこのスナップショットである。

コミットは、テーブルのメタデータを1回のアトミックな操作で変更する。そのため、読み手はコミットの前のテーブルか後のテーブルのどちらかを見ることになり、途中の状態を見ることはない。Apache Icebergでは、コミットのたびにスナップショットが作られる。Icebergの仕様は、スナップショットを「ある時点におけるテーブルの状態」と定義し、テーブル内のデータファイルの完全な集合にアクセスするために使うものとしている。また、各変更をメタデータファイルのアトミックな差し替えとして記述している。スナップショットは、一意のID、作成時刻、サマリーを持つ。サマリーには必須のフィールドoperationがあり、その値はappend、replace、overwrite、deleteのいずれかである。appendはデータファイルを追加し、何も削除しなかったことを表す。後続のコミットは新しいスナップショットを追加するだけで、以前のスナップショットには手を加えない。このため、ダッシュボードの管理者は、すでに最新ではなくなった状態についても問い合わせることができる。

スキャンを行う前に、まず履歴を読む。この例は、3回のコミットを順に、各コミットの操作と追加された行数とともに一覧表示する。表示は、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

3回のコミットはいずれもappendであり、ファイルを書き換えたり削除したりしたものはない。00時のコミットでは499行が追加された。他の時間より1行少ないのは、データの切り出しでこの時間から1行が除かれたためであり、、その理由はデータのREADMEで説明されている。01時と02時のコミットでは、それぞれ500行が追加された。管理者の疑問はここから始まる。テーブルには選べる状態が3つあり、履歴がそれらを名指ししている。

pyicebergは、各スナップショットに長整数のIDを割り当てる。本書ではこれらのIDを表示しない。代わりにsnapshot_labelsがコミット順にIDを「snapshot 1」「snapshot 2」「snapshot 3」というラベルに対応づけ、出力にはラベルだけを表示する。

同じ3時間分のデータを、write_deltalakeを通じてDelta Lakeのテーブルにも書き込んだ。書き込みは1時間につき1回である。Delta Lakeは各コミットをバージョンと呼び、その履歴には、バージョンごとに操作と書き込まれた行数が並ぶ。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 では、スナップショットはマニフェストリストを記録し、そこからファイルが見つかる。前の節の定義は、スナップショットをデータファイルの完全な集合への入り口としている。そのため、読み手はスナップショットから出発し、それをたどってファイルに行き着く。

このことから、スナップショットはポインタの集合となる。この帰結は、以降のすべての節に関わる。スナップショットが読めるのは、それが名指しするファイルがまだ存在しているあいだに限られる。したがって、タイムトラベルはバックアップではない。タイムトラベルが読めるのはテーブルがまだ保持しているファイルだけであり、テーブルがファイルを保持するのは、いずれかのスナップショットがそのファイルを名指ししているあいだに限られる。第 7 章では、古いスナップショットと、それらだけが名指ししていたファイルを削除する。これにより、そうした状態へのタイムトラベルはできなくなる。

コミットの操作種別から、どのような共有が可能かがわかる。仕様は、appendを「データファイルが追加されただけで、削除されたファイルはない」操作と定義している。そのため、3 番目のコミットは 00 時台のファイルを書き換えていないので、スナップショット 3 は 00 時台のファイルを再び名指しする。複数のスナップショットが同じファイルを名指しでき、コミットのコストは、そのコミットが書いたファイルとそれらへのポインタだけで済む。

pyiceberg でのスナップショットの行数は、ポインタの働きを示している。スナップショット 2 は 999 行を読み戻す。これは 00 時台の 499 行と 01 時台の 500 行の合計であり、02 時台の行は含まれない。スナップショット 3 は 3 つの時間帯すべてを読む。各スナップショットは、その時点までのコミットで可視になった行を読み、それ以上は読まない。2 つの行数の差は 3 番目のコミットが追加した行であり、その数は 500 行である。このように、履歴と読み取り結果は一致する。

実践ルール: 古いスナップショットは、そのファイルが存在するあいだだけ読めるものとして扱う。ファイルを削除する前に、どのスナップショットを残すかを決め、それ以外を先に期限切れにする。クリーンアップ後に古いスナップショットへのクエリが失敗した場合、その原因はファイルの欠落である。対処は、そのファイルをテーブルのコピーから探し出すことであり、代わりに別のスナップショットを読むことではない。

過去のスナップショットを読む

過去のスナップショットを読むとは、テーブルをスキャンするときにそのスナップショットを指定することである。指定の方法は形式ごとに異なる。Iceberg はスナップショット ID を受け取る。DuckLake は AT (VERSION => n) でスナップショット番号を受け取る。Delta Lake はバージョン番号を受け取る。この三つの番号は、同じものを数えているわけではない。

所有者が最初に知りたいのは、3 時間目のデータが書き込まれる前の合計がいくらだったかである。その答えは、2 回目のコミットの後の状態、つまりスナップショット 2 である。

pyiceberg のスナップショット

最終変更:版2026.11.7

pyiceberg 0.12.0 では、scan(snapshot_id=...) はそのスナップショット時点のテーブルを読み取り、スナップショット ID を指定しないスキャンは現在のスナップショットを読み取る。ID を指定した 2 回のスキャンにより、所有者の最初の質問にテーブル自身の履歴から答えられる。この例では、現在のテーブルも読み取り、スナップショット 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 は、所有者の最初の質問に答えている。3 回目のコミットの前には、テーブルの閲覧数は合計で 580963 であり、コミット後のスナップショット 3 では 899451 である。ID を指定せずにテーブルを読み取ると、スナップショット 3 と同じ行が得られる。この確認では、行数だけでなく行そのものを比較している。

views 列は、所有者の 2 番目の質問に答えている。スナップショット 3 の閲覧数はスナップショット 2 より多く、その差は 02 時台に加わった閲覧数である。合計が変わったのは、3 回目のコミットで行が追加されたからであり、ダッシュボードのクエリが変わったからではない。同じテーブルを 2 回読み取れば、クエリを何も変更せずにそのことを示せる。

「スナップショット 2」というラベルを念頭に置いている読者は、数値 2 を ID として渡してしまうかもしれない。その呼び出しは失敗するが、この失敗は安全な結果である。

ValueError: Snapshot not found: 2

エラーは、渡された数値を示し、それがスナップショット ID ではないことを伝える。テーブルには何も変更が加わらない。読者はそこで、ID を調べる必要があると分かる。この例自体は、各 ID を table.snapshots() から調べており、件数から ID を計算することはない。ラベルは本文のためにあり、ID はスキャンのためにある。

実践ルール: スナップショット ID は table.snapshots() から取得し、調べた ID を渡すこと。ラベルの番号を渡してはならない。何かを出力する前に、コミット順に ID をラベルへ対応付ける。知りたいのがあるコミット後の状態であれば、まず履歴でそのコミットを探し、そのコミットが作成したスナップショットを読み取る。

各形式でコミットを番号によって読む

最終変更:版2026.11.10

Delta Lake では、DeltaTable(path, version=n) によって以前のバージョンを読む。バージョンとは、テーブルの履歴におけるコミットの位置であり、0 から数える。したがってバージョン 0 が最初の書き込みである。ヘルパー read_delta はパスと省略可能なバージョンを受け取り、行をソート済みの Arrow テーブルとして返す。本書では、Delta の読み取りはすべて deltalake の QueryBuilder を経由し、ヘルパーがこれを呼び出す。その理由は判断の節に理由が述べてある。

DuckLake は、カタログへの変更ごとにスナップショットを保持する。この変更には、スキーマの作成やテーブルの作成も含まれる。DuckLake もスナップショットを 0 から数えるため、新しいカタログでの最初の insert は 1 番ではない。DuckLake のタイムトラベルのページは、スナップショットを読むための句 SELECT * FROM tbl AT (VERSION => 3); を示し、問い合わせるスナップショットはタイムスタンプで、あるいは「スナップショット識別子を明示して」指定できると述べている。本書では識別子を用いる。番号は、自分で数えた insert の回数からではなく、ducklake_snapshots から読み取る。

3 つのバージョン番号の例は、行数は一致するのに番号は食い違う状況を作り出す。同じ 3 時間分のデータを Delta テーブルと DuckLake テーブルに書き込み、各形式で 1 時間につき 1 コミットとする。そのうえで各コミットを番号によって読み戻し、両者の行数を表示し、最初の insert より前の DuckLake のスナップショットを数え、1 つの失敗例を示す。

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'

最初の insert が「スナップショット 1」ではなく「スナップショット 4」となるのは、その前に DuckLake のカタログがすでに 3 個のスナップショットを保持しているためである。その内訳は、attach 時に DuckLake が作成する既定のスキーマ、wiki スキーマ、そしてテーブルである。本書は、セットアップを含めて DuckLake のスナップショットを 1 から数えてラベルを付ける。そのため「スナップショット 4」は DuckLake 自身の番号 3 に 1 を足したものである。insert を 1 から数える読者は、誤ったラベルを得ることになる。

各時間の後には、2 つの形式は、コミットの番号の付け方が異なるにもかかわらず、同じ行数を保持している。両形式は番号体系を共有しないので、両者を対応づけるキーは時間である。完全なテーブルとなる時間 02 の後では、Delta のバージョン 2 は 1499 行、DuckLake のスナップショット 6 は 1499 行を持ち、それ以前の時間も同様に一致する。

次の表は、3 つの番号を並べて示したものである。

形式 コミットを指す番号 数え上げる変更 読み方
Iceberg スナップショット ID(long 整数) テーブルへの各コミット scan(snapshot_id=...)
Delta Lake バージョン(0 から数える) テーブルへの各コミット DeltaTable(path, version=n)
DuckLake スナップショット番号(0 から数える。本書のラベルは 1 大きい) スキーマやテーブルの作成を含む、カタログへのすべての変更 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 ではなくラベルを用いる。 出力される行には、Iceberg と DuckLake について「snapshot 2」のようなラベルを付けた。ラベルは、形式が記録するすべてのスナップショットを 1 から数えたものである。DuckLake では、これに 3 つのセットアップ用スナップショットが含まれるため、DuckLake 自身の番号はラベルより 1 小さい。Iceberg の ID と DuckLake のスナップショット番号は、出力には現れない。Delta はバージョン番号をそのまま出力する。この番号は 0 から数え、読者が DeltaTable に渡す番号である。読者は例を再実行し、その出力を 1 行ずつ比較できる。差分に現れるのはデータやライブラリの変化だけであり、ランダムな ID の変化が現れることはない。ラベルはコミット順に対応付けるため、ライブラリが履歴を別の順序で返しても、ラベルの意味は変わらない。
  • タイムスタンプではなく ID とバージョン番号を用いる。 タイムスタンプによる読み取りは、時計と各コミットを実行した時刻に左右される。本書では ID または番号で読み取る。そうすれば、例をいつ実行しても、同じコミットから同じ行が得られる。本番環境で実時間が必要な読者は、タイムスタンプ形式を用い、各コミットを実行した時刻の記録を保持するとよい。
  • Delta は read_delta だけで読み取る。 ヘルパーは deltalake の QueryBuilder を通して読み取る。これらの固定バージョンでは、第 8 章で測定したとおり、to_pyarrow_table() 経路は実行によっては終了時に異常終了する。異常終了を回避策で避けるのではなく、読み取り経路のほうを固定する。そのため、どの例も os._exit を呼ばず、終了ステータスを隠すこともない。
  • DuckLake はヘルパーだけを通して使う。 DuckLake の実行ではすべて、connect_ducklake で DuckLake を読み込み、attach_ducklake でアタッチする。allow_unsigned_extensions は一度も設定しない。本書の実行では、リポジトリ内に同梱したファイルから、DuckDB の公式の署名付き DuckLake 拡張を読み込む。その際、ヘルパーが両方のハッシュを SOURCE.toml と照合してから読み込むので、オフラインでの実行でもダウンロードは要らない。読者自身のマシンで、同梱ファイルがない場合に限り、connect_ducklake は INSTALL ducklake を実行する。
  • カタログへのクエリは範囲を絞る。 ducklake_snapshots へのクエリは列名を明示し、snapshot_time は含めない。この列には、固定バージョンがインストールしないモジュールが必要だからである。固定バージョンに記録されない依存関係を加えるよりも、必要な列を名指しするほうがよい。
  • Delta は独自の番号を保つ。 Delta は 0 から数えた実際のバージョンを出力する。各ラベルが示すのは、そのコミットが自身のテーブルの中でどれにあたるかだけであり、2 つの形式が同じ状態を保持していることは示さない。それを確認するのは、ラベルごとの行数の比較である。
  • 失敗は送出せず出力する。 2 つの例は、意図的に失敗する呼び出しで終わる。それぞれの例はエラーを捕捉して出力する。失敗を示すのは、読者がそれに出会うからであり、エラーのテキストは全文を出力するので、読者は自分の出力と照合できる。
  • 状態の前に履歴を読む。 コードは各形式のコミットを一覧し、そのあとで番号を指定してコミットを読み取る。この章の読者は、スキャンの前に、各コミットの操作と行数を得られる。そのため、行数がおかしく見えるときは、それを生んだコミットと照らして確認できる。

この版における本章

第2026.11.10版2026年11月20日時点で例が通過この章の3 例件のうち3件が合格

英語版の書籍(版2026.11.10)から翻訳した。

この節を引用する

形式

いずれの形式も、本訳書が従う英語版の書籍を出典として示す。

いずれの形式もこの版を明示している。そのリンクは現行版を開き、節の見出しには本文が最後に変更された日付が示される。アクセス日と取得日は、これを開いた日である。

このページの内容

全10章中の第2章: 以前のスナップショットの時点のテーブルを読む

  1. すべてのコミットがスナップショットになる
  2. スナップショットが指すもの
  3. 過去のスナップショットを読む
  4. pyiceberg のスナップショット
  5. 各形式でコミットを番号によって読む
  6. What goes wrong in production
  7. この章で下した決定

ページの先頭に戻るすべての章