テーブルをカタログに登録し、DuckDB から問い合わせる

読了まで約35 分分、8 節 節の 5 例 例。

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

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

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

この章では、Iceberg テーブルを SQL カタログに登録し、DuckLake カタログをアタッチし、Delta Lake テーブルをそのパスで開き、Iceberg のテーブルと DuckLake のテーブルを結合する DuckDB の文を 1 つ実行する。あわせて、各カタログが何を保持しているか、カタログとデータファイルの内容が食い違ったときにテーブルがどうなるかを学ぶ。

これまでの章では、各テーブルをそれぞれの経路で開いてきた。Iceberg ではカタログオブジェクト、DuckLake ではファイル、Delta Lake ではフォルダである。最初のテーブルでは、wiki.pageviews_hourly を Iceberg の SQL カタログに local という名前で登録した。この章では、その名前が何の役割を果たすのか、また各フォーマットがそれに代えて何を用いるのかを説明する。さらに 2 つ目のテーブル wiki.domains を追加する。これはドメインコードと、各コードが表す言語を並べた 4 行の一覧である。このテーブルは DuckLake カタログに置かれ、結合の節で Iceberg のページビューと結合する。

カタログが保持するもの

最終変更:版2026.11.10

wiki.pageviews_hourlyがどこにあるかを尋ねると、答えは形式によって異なる。内部では、どの形式もテーブルをデータファイルとメタデータファイルとして保存している。メタデータはテーブルの現在の状態を示す。具体的には、スキーマ、パーティション仕様、そして現在のスナップショットまたはバージョンのデータファイルであり、データファイルは直接、またはマニフェストファイルを介して示される。コミットのたびに新しいメタデータが書き込まれ、テーブルはそのメタデータへ移る。カタログは、テーブル名と、そのテーブルの現在のメタデータの所在とを対応づける登録簿である。wiki.pageviews_hourlyについてカタログに問い合わせた読み手は、メタデータへのポインタを受け取り、そのメタデータが列挙するデータファイルを読む。

カタログが保持するのはポインタであり、行そのものではない。Parquetファイルはウェアハウスのフォルダに残り、カタログは読み取りをどこから始めるかを示す。名前には第二の階層もある。wikiは名前空間であり、本書に登場するIcebergのテーブル名はすべて、名前空間とテーブル名をドットでつないだものである。

カタログの選択は二つの問いに集約される。誰がテーブルに書き込むのか、そして何がそれを読むのか、である。一つのジョブが書き込み、一つのエンジンが読むテーブルは、ファイルベースのカタログに置き、パスで見つけることができる。複数のエンジンが読むテーブルには、そのすべてが解決できる名前が必要であり、それを提供するのがSQLカタログやサービスである。テーブルごとにカタログを一つにすること、そしてテーブルのそばに、そのカタログと所有者を記した記録を置くことを推奨する。結合の節で示すように、カタログをまたぐ結合は一つのセッション内で実行できる。しかし、それによって二つのカタログが一つになるわけではない。

本書で扱う三つの形式は、三種類の異なるカタログを使う。

形式 テーブルに名前を与えるもの 現在のメタデータの所在
Iceberg SQLカタログのオブジェクト(ここではlocalと名づける) カタログのデータベース。メタデータファイルを指す
DuckLake パスでアタッチされるカタログファイル カタログファイルの内部
Delta Lake なし。テーブルのフォルダパスがそれに当たる テーブルのフォルダ内

IcebergのRESTカタログは、ファイルではなくサービスという、別の種類のカタログである。そのRESTカタログのページは、任意のIcebergカタログとやり取りするための、OpenAPIで仕様化された共通APIを説明している。これにより、クライアントはすべてのカタログに対して一つの実装を用意すれば足りる。同ページによれば、このプロトコルは変更ベースのコミットを用いるため、サービス側で競合を解決して再試行でき、ルートメタデータはカタログサービスが書き込む。本章ではRESTカタログを実行しない。RESTカタログはいずれも稼働中のサービスを必要とするが、本章の例はサービスなしのオフラインで動作するからである。このプロトコルを実装する各製品の比較は、本書では扱わない。

カタログは名前以外のものを保持することもある。分類や保持ルールもテーブルのメタデータである。これらはData Governance as Codeで扱われており、本書では教えない。

実践ルール: テーブルに書き込む前に、そのテーブルに名前を与えているカタログまたはパスを確認し、データフォルダとあわせてそのカタログもバックアップする。Parquetファイルはテーブルに名前を与えない。名前を与えるのはカタログである。これは障害の節で示す。

SQL カタログにテーブルを登録する

最終変更:版2026.11.7

pyiceberg のSqlCatalogは、テーブルをデータベースに保持する。このデータベースにはuriを、データファイルとメタデータを書き込むフォルダにはwarehouseを指定する。本書では、データベースに SQLite ファイルを、ウェアハウスにローカルフォルダを使う。pyiceberg configuration pageによると、SQL カタログには背後にデータベースが必要であり、SQLite は並行処理を想定して作られておらず、探索的な用途や開発用途に向くと警告している。ここでの例は開発用であるため、この制限は例の動作に影響しない。本番環境のカタログには、複数の書き込み側が使えるデータベースが必要である。

次の例では、同じカタログファイルを同じ名前でもう一度開き、その 2 つ目のオブジェクトを通してテーブルを読む。続いて、テーブルのメタデータに 2 つ目の名前を登録し、名前の異なるカタログオブジェクトから何が見えるかを示す。

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

2 つ目のオブジェクトは、wiki.pageviews_hourlyの1499行を読み取る。これは第 1 章で取り込んだ 3 時間分である。pyiceberg は、SqlCatalogに渡したカタログ名のもとに各テーブルを保存する。同じ名前のオブジェクトは、同じテーブルを見つける。

カタログとウェアハウスのフォルダは対になっている。カタログはメタデータファイルの場所を保持しており、その場所はwarehouseプロパティが指すフォルダの下にある。ウェアハウスのフォルダのないカタログファイルのコピーや、ファイルのないフォルダは、存在しないファイルを指すポインタを残すだけである。両方をバックアップし、両方を一緒に移動すること。

各プロセスは自分のカタログオブジェクトを開き、他のプロセスと状態を共有しない。ここでは、1 つのプロセス内の 2 つのオブジェクトが 2 つのプロセスの代わりを務める。

読み込まれたテーブルは、読み込んだ時点の状態を保つ。4 時間目の追記より前に読み込んだオブジェクトは今も1499行を読み取るが、再読み込みすると1999行を読み取る。開始時にテーブルを読み込み、終了時にそれを読むプロセスは、開始時点の状態を読むことになる。その間に行われたコミットを見るには、再読み込みが必要である。

実践ルール: SQL カタログファイルは、コードのどこでも同じ名前で開くこと。テーブルを読み込んだ後に別の書き込み側がコミットした可能性があるときは、読む前にテーブルを再読み込みすること。SQLite は一度に 1 つの書き込み側だけに使い、複数の書き込み側を動かす前に、並行書き込み向けのデータベースへ切り替えること。

メタデータファイルからテーブルを登録する

最終変更:版2026.11.7

register_table(identifier, metadata_location) は、既存のメタデータファイルに名前を追加する。pyiceberg API ページは、これをメタデータからテーブルを登録する方法として示しており、overwrite=True を渡すと既存のエントリが置き換えられると説明している。この例では、先に作成した名前空間の中に、テーブルのメタデータを archive.pageviews_copy として登録する。アーカイブ側の名前は元のテーブルと同じ行を読み取り、その行数は 1999 である。2 つの名前は同じメタデータを指しており、登録によってデータファイルが書き込まれることはない。

登録した名前は、同じテーブルへのもう 1 つの経路であり、2 つ目のテーブルではない。両方の名前が同じメタデータを読むため、一方の名前を通したコミットは両方の名前のコミットになる。2 つ目の名前は読み取り用の経路として扱い、バックアップとして扱ってはならない。

実践ルール: 1 つのテーブルにつき、書き込み用の名前は 1 つだけにする。メタデータファイルを 2 つ目の名前で登録するのは、後で削除する読み取りのためだけにする。overwrite=True を渡すのは、そのエントリを置き換える意図があるときだけにする。

この部分はまだ翻訳されていないため、英語で表示している。

Attach a DuckLake catalog

最終変更:版2026.11.7

DuckLake's catalog is a database file, and DuckDB attaches it with an ATTACH statement that starts with ducklake: and gives the file's path. The data path, the folder where DuckLake writes Parquet files, is stored in the catalog. The DuckLake connecting page says the data storage location only has to be given when a new DuckLake is created, and that the location is loaded from the catalog database after that. The helper connect_ducklake loads DuckLake into the DuckDB session with downloads off, and attach_ducklake runs the ATTACH for a catalog file under a folder.

The next example creates wiki.domains in a fresh DuckLake catalog, detaches it, and attaches the file again with no data path. It then lists the tables in the wiki schema of the file.

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

The 4 rows of wiki.domains are written, and 4 rows read back after the re-attach. The table list shows one table in the wiki schema, domains. The second attach needed no data path, because the file already held it. The listing comes from the catalog, not from the data folder. The catalog file holds the list of tables, and the data folder holds the bytes. Losing the first loses the names even when the second is intact, as the failure section shows.

The same connecting page says that DuckLake inlines small inserts into the catalog database, with a default limit of 10 rows. The helper this chapter uses sets the inlining limit to 0, so every insert in these examples becomes a Parquet file in the data folder, the setting chapter 1 explains. Without that setting, a small table lives in the catalog file, and a copy of the data folder would not hold its rows. That is one reason the catalog file needs a backup of its own.

Working rule: Back up a DuckLake catalog file with the data folder, and copy the file while no session has it attached. Give the data path when you create a catalog, and attach later with the catalog file alone.

カタログを使わず、パスでテーブルを見つける

最終変更:版2026.11.7

本書における Delta Lake のテーブルは、1 つのフォルダである。カタログはなく、本書のセットアップにはパス以外にテーブルを指す名前もない。deltalake パッケージは DeltaTable(path) でそのフォルダを開き、すべての読み取りはそのパスを通して行われる。次の例の 3 回の追記は、バージョン 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 には最初の 1 時間分だけの 499 行がある。ここでの行は read_delta を通して取得され、Arrow テーブルが返る。本書が Delta テーブルをこのように読む理由は、この章の最後にある決定事項で述べる。

パスが名前のすべてなので、パスの誤記はテーブルが存在しないことを意味する。この例では存在しないフォルダを開こうとしており、DeltaTable は TableNotFoundError を送出する。エラーは試みたパスを示すが、それは誤ったパスが実際に使われた後のことである。したがって、確認はパスを組み立てるコードの中で行うべきである。

パスは、1 つのジョブが書き込み、少数のジョブが読み取るテーブルの名前として適している。サービスもセットアップも必要としない。しかし、欠点もある。パスはテーブルがどの名前空間にあるかを示さないため、異なる場所にある同じフォルダ名の 2 つのテーブルは、読み手には同一に見える。名前でテーブルを見つけたいエンジンは、参照できるものを何も持たない。本書の Delta テーブルは小さくローカルにあり、パスで十分である。複数のエンジンが読み取る共有レイクでは、Delta Lake のテーブルのためにカタログが必要になるが、本書ではカタログを扱わない。

実践ルール: 各 Delta テーブルのパスは、設定値のようにコードが読み取る 1 か所に保持する。ジョブの開始時にテーブルを 1 度開いて、パスを確認する。存在しないパスは空のテーブルではなく、エラーである。

2つのカタログのテーブルを結合する

最終変更:版2026.11.7

DuckDB は、ライブラリから渡された Arrow テーブルと、同じセッションにアタッチされた DuckLake テーブルを、1つの文で問い合わせることができる。Iceberg テーブルは、scan_arrow を通じて pyiceberg から Arrow テーブルとして取り出される。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 行は言語を持たないまま残る。閲覧数の上位3件は同じページであり、英語ドメインの Main_Page である。

結合キーは domain_code であり、両側とも文字列である。大文字と小文字、または末尾の空白が異なるキーで結合すると、どの行も一致しない。その場合、結合後の行数は 0 になり、言語を持たない行の数はテーブルの行数と等しくなる。結合を信頼する前に、同じセッションで両側のキーを確認すること。

このクエリが成立するのは、両側が1つの DuckDB セッションで出会うからである。2つのテーブルが1つになるわけではない。それぞれが自身のコミットを保持し、Arrow テーブルは scan_arrow を実行した時点の Iceberg テーブルのスナップショットである。別の書き込み側が変更中のテーブルに対して結合を行うと、その時点で最新だった状態が読まれる。

カタログをまたぐ結合は、今回のような参照用途に勧める。つまり、小さなディメンションテーブルを自身のカタログに置いたまま、大きなテーブルに対するクエリから読む場合である。あるテーブルが、別のテーブルを読むほぼすべてのクエリに現れるなら、それらのクエリが使うカタログにそのテーブルをコピーする。第9章ではテーブルを形式間でコピーし、各コピーを検証する。テーブルをどこかへ移す前に行うべき手順は、この検証である。

実践ルール: カタログをまたぐ結合を1つのセッションで行うのは、Arrow として読む側がメモリに収まる場合に限る。読む前にその状態を選び、一致する相手が見つからない行を数える。その数は 0 であるべきである。

この部分はまだ翻訳されていないため、英語で表示している。

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 カタログに登録する。 本書のカタログ名は 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 カタログには、実行できる例がない。 REST カタログにはネットワークが必要であるため、この章ではそのページに基づいてプロトコルを説明し、特定の製品については何も主張しない。

この版における本章

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

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

この節を引用する

形式

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

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

このページの内容

全10章中の第8章: テーブルをカタログに登録し、DuckDB から問い合わせる

  1. カタログが保持するもの
  2. SQL カタログにテーブルを登録する
  3. メタデータファイルからテーブルを登録する
  4. Attach a DuckLake catalog
  5. カタログを使わず、パスでテーブルを見つける
  6. 2つのカタログのテーブルを結合する
  7. What goes wrong in production
  8. この章で行った決定

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