ツールが対応する機能からフォーマットを選ぶ
読了まで約33 分分、11 節 節の 5 例 例。
この章を読み終えると、テーブルを読み書きするすべてのツールを一覧にし、各ツールが固定されたバージョンで何に対応しているかを測定し、その測定結果からフォーマットとその機能を選べるようになる。
第1章から第9章を通じて、1つのテーブル wiki.pageviews_hourly が、Apache Iceberg、Delta Lake、DuckLake の3つのフォーマットで、その一生を過ごした。各フォーマットは同じ作業をそれぞれ異なる方法で行い、各ライブラリが対応する作業の範囲もそれぞれ異なっていた。ここで問われるのは、一般にどのフォーマットが最良かではない。チームのすべてのツールが、実際に使っているバージョンで、開き、変更し、後始末までできるフォーマットはどれか、という問いである。この章では、それを測定する方法を示し、本書で固定したバージョンでの測定結果を示したうえで、選択のための短い指針を与える。
この選択は読み手によって決まる。実行例の wiki.pageviews_hourly には読み手が3つある。DuckDB 経由でクエリを実行するダッシュボード、pyiceberg で追記するパイプライン、そして deltalake 経由で Delta Lake のコピーを読むアーカイブジョブである。各読み手にはそれぞれ固定されたバージョンがあり、それぞれが他の読み手の書いたデータを開けなければならない。この章の残りは、この状況に備えるためのものである。
この選択が見かけより難しいのは、3つの理由による。第一に、フォーマット間で最も差が大きい機能、たとえば削除、名前の変更、パーティションの変更は、チームが最初に必要とする機能でもある。第二に、各ライブラリは独自のスケジュールで変更されるため、あるツールがあるバージョンで読めるテーブルが、別のバージョンでは開けないことがある。第三に、1台のマシンで検査に通っても、他のツールが動かすバージョンについては何も保証されない。この章の各節では、これらを順に扱う。
選ぶ前にサポートを測定する
フォーマット名を見ても、ツールが何をサポートしているかは分からない。サポートは、特定のバージョンのツールに属するものである。書き込み側が作成できる機能を、読み取り側が開けないことがある。また、ベンダーのページが説明しているのはそのベンダーのエンジンであり、手元のノートパソコンにあるライブラリではない。したがって、フォーマットからではなく、読み取り側から始める。テーブルを読むすべてのツールをバージョンとともに書き出し、使う予定の各機能をそれらのバージョンごとにテストする。
以下の各測定は、読み取り側から始めて、その上で一つの機能をテストする。pyiceberg には、フォーマットバージョン 2 のテーブルで削除を実行させ、続いてバージョン 3 を要求する(iceberg-format-versions)。deltalake では、削除ベクトルを有効にして読み戻す(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 release calendar)。DuckLake 1.0 は 2026 年 4 月 13 日にリリースされた(DuckLake release calendar)。これらの固定バージョンでは、カタログはバージョン 1.1 を報告し、読み手が開くべきバージョンはこれである。拡張のバージョンは別である。DuckDB はそのビルドを 417a9117f5 と報告し、拡張は DuckDB 2.0.0 に同梱されるため、拡張のバージョンは DuckDB のバージョンに従う。最後の列には、各セルの根拠となる例または出典を示す。「Not shown here」は、本書に記載がないことを意味し、機能が存在しないことを意味しない。
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 | 掲載箇所 |
|---|---|---|---|---|
| 行をコミットとして書き込む | 可 | 可 | 可 | 3 時間分を書き込む |
| 番号を指定して以前のコミットを読み取る | 可(スナップショットで指定) | 可(バージョンで指定) | 可(スナップショットで指定) | Iceberg、Delta と DuckLake |
| フォーマットバージョン 3 を作成する | 不可、エラーが発生する | — | — | 例 |
| 列名を変更する | 可(フィールド ID による) | 不可、何も起こらず通知もない | ここでは示さない | Iceberg、deltalake |
| 作成時の列マッピング | — | 可 | — | deltalake |
変更とクリーンアップ
| 変更とクリーンアップ | pyiceberg | deltalake | DuckLake | 掲載箇所 |
|---|---|---|---|---|
| 行の削除 | ファイルを書き換える | ファイルを書き換える | 削除ファイルを書き込む | 第5章 |
| 削除ファイルの書き込み | なし | なし | あり(インライン化された場合を除く) | フォーマットバージョン、機能の確認、DuckLake、インライン化 |
| アップサートまたはマージ | アップサート、複数のスナップショット | ここでは扱わない | MERGE INTO |
アップサート、MERGE |
| パーティショニングの変更 | 古いファイルは古い仕様を保持する | スキーマモードで上書きする | ALTER TABLE で変更する |
第4章、その他のフォーマット |
| 小さなファイルのコンパクション | 方法はない。テーブルを上書きする | optimize.compact() |
隣接するファイルを統合する | Iceberg、deltalake、DuckLake |
| スナップショットの期限切れ処理 | ID または 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 は version 3 のテーブルを書き込まない
Iceberg 仕様の version 3 の節は、バイナリ形式の削除ベクトル(deletion vector)を行レベルの削除形式としている。同節は「ライターは v3 テーブルに新しい位置削除ファイルを追加してはならない」と述べている(Iceberg spec)。同じ節では、新しい行のための行リネージ、列のデフォルト値、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 が発生するため、このライターからは version 3 の機能を一切利用できない。
これらの固定バージョンの pyiceberg は、フォーマットバージョン 2 が削除ファイルも認めているにもかかわらず(5 章)、対象となるデータファイルを書き直すことで削除を行う。このテーブルでは 82 行が削除され、削除ファイルは 0 個である。二つのスナップショットは、append と、削除に対応する overwrite である。選択の前に、自分のテーブルのコピーでこの書き直しを測定すること。
| 機能 | Iceberg v3 仕様 | 固定バージョンの pyiceberg |
|---|---|---|
| バイナリ削除ベクトル | 行レベルの削除形式 | 書き込まない |
| 位置削除ファイル | レガシー。フォーマットバージョン 2 のテーブルでのみ使用 | 書き込まない |
| 行リネージ、デフォルト値、variant、ナノ秒タイムスタンプ | version 3 の一部 | 利用不可: version 3 のテーブルがない |
実践ルール: 固定バージョンの pyiceberg ではフォーマットバージョン 2 を書き込み、どの読み手にも version 3 の機能を約束してはならない。version 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 であり、リーダーはそのすべてを実装していなければならない。今回設定したのは削除ベクトルの設定だけであり、残りの 2 つの機能は deltalake が自動的に追加した。
このバージョン固定の環境では、deltalake は機能を宣言するものの、実際にはファイルを書き換えることで削除を行う。閲覧数が 180 未満の行を削除した結果、削除された行数は 82、書き換えられたデータファイル数は 1 であり、テーブルが持つ削除ベクトルファイルは 0 個である。その後に QueryBuilder が読み取る行数は 417 である。本書では、第 8 章で示すとおり、Delta テーブルを QueryBuilder 経由でのみ読み取る。
問題になるのは削除ベクトルだけではなく、リスト内のすべての機能である。timestampNtz や variantType を持たないリーダーは、deletionVectors を持たないリーダーと同じ問題を抱える。変更を加えるたびに、出力された機能リストを各リーダー自身のリストと照合する。
したがって、削除ベクトルの設定はテーブルのすべてのリーダーに対するプロトコル変更であり、書き込み自体はどのリーダーも試されないうちに成功する。有効にするのは、対象とするすべてのリーダーが deletionVectors 機能を実装している場合に限る。そうでなければ、コピーオンライトを維持する。
ここでいうリーダーの検査とは、最初の本番書き込みの前に、リーダー自身のインターフェースを通してテーブルを開くことである。この事例の Delta Lake のコピーでは、その検査は QueryBuilder 経由の読み取りとプロトコルの読み取りであり、どちらも feature-check の例に含まれている。
実践ルール: 削除ベクトルを有効にするのは、各リーダーの機能対応をそのリーダー自身のバージョンで確認した後に限る。変更のたびにテーブルのプロトコルを読み戻し、検証済みの範囲外のリーダーが開く可能性のあるテーブルには、コピーオンライトを維持する。
新しいテーブルのためのチェックリスト
複数のツールが開くテーブルを作成する前に、このリストを使う。各項目は、サポート表と削除ベクトルの節で示したリスクを一つずつ解消するものである。
- すべてのリーダーとライターを、そのバージョンとともに一覧にする。一覧から漏れたツールは、テストしていないリーダーであり、失敗するのはそのリーダーである。
- テーブルが必要とする各機能について、本章の例と同じように、各ツールでのサポートを測定する。ライターだけでなくリーダーも測定する。書き込みが成功しても、証明されるのはライターがファイルを生成できることだけだからである。
- フォーマットバージョンとプロトコルは意図して設定する。設定した値を読み戻し、各リーダーからテーブルを読む。自分で選んでいない既定値を受け入れてはならない。
- 組の中の一つのリーダーでもサポートしていないフォーマットバージョンや機能は採用しない。一つのリーダーが開けないテーブルは、他のリーダーにとってどれほど優れた機能を備えていても、障害である。
- 名前変更は、測定したサポートが許す場合にのみ約束する。Iceberg はフィールド ID によって名前を変更する。deltalake には、これらの固定バージョンでは名前変更がないため、代わりに書き直しを計画し、その後で列名を確認する。
- すべてのリーダーを削除ベクトルでテストし終えるまでは、削除には単純なコピーオンライトの経路を残す。コピーオンライトはファイルの書き直しというコストを払うが、どのツールでも開ける。
- アップグレードは、リーダー、ライター、プロトコルの順に計画する。各段階の後にテーブルを読み、リーダーが失敗したら中止する。
- 固定バージョンを変更するたびに測定をやり直し、新しいバージョンをリーダーの表に記録する。
実践ルール: このリストはテーブルの設計メモとともに保管する。そうすれば、次にリーダーを追加する人が同じ記録から始められる。最新の状態に保ったリストは、読み取りに失敗した後で作り直すリストよりも手間がかからない。
読み手から形式を選ぶ
この指針は、読み手を測定したあとに使う。最初の列は形式ではなく状況である。この表は、測定した読み手の集合を形式に対応づけるものであり、測定の代わりにはならない。
| 状況 | 選ぶ形式 | 理由 |
|---|---|---|
| pyiceberg と DuckDB がテーブルを読む | Iceberg、フォーマットバージョン 2 | pyiceberg が読み、DuckDB がその出力に対してクエリを実行する |
| 複数の読み手がいて、インプレースの名前変更が必要 | Iceberg | 3章で示すとおり、名前を変更してもフィールド ID は保たれる |
| 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)。本書の例には、この拡張を実行するものはない。例は実行時に何もインストールせず、各形式自身のライブラリを使う。そのため、読者はテーブルを書き込むライブラリと同じものを目にすることになり、例の実行中にダウンロードも発生しない。
表は行ごとに読む。二つの行が異なる方向を指す場合は、読み手が決め手になる。まず、測定した集合のすべての読み手が開ける形式を選び、次にすべての読み手がサポートする機能を選ぶ。
この指針を、継続して扱っている事例に当てはめる。ダッシュボードとパイプラインは、どちらも pageviews テーブルを pyiceberg または DuckDB で開くので、Iceberg フォーマットバージョン 2 が適している。アーカイブジョブは Delta Lake のコピーを読むため、Delta の行が当てはまるのはそのコピーだけであり、コピーでは削除をコピーオンライトのまま保つ。
複数のツールが読むテーブルの既定には、Iceberg フォーマットバージョン 2 を推奨する。pyiceberg が書き込み、DuckDB がその出力を読み、例で両方を測定しているからである。このピン留めでのコストは次のとおりである。削除のたびに、対象となるデータファイルが書き直される。テーブルにはカタログが必要である。pyiceberg には、コンパクションや孤立ファイルの削除を行う呼び出しがない。DuckDB が唯一のエンジンである場合は、DuckLake を推奨する。読み手と書き手が一つの SQL の範囲を共有するからである。そのコストは次のとおりである。読み手が DuckDB に限られる。カタログのバージョンが DuckDB のリリースに結びついている。小さな削除は、インライン化を無効にしない限りインライン化される。この章の確認によって、必要なことを読み手ができないと分かった場合は、別の選択をする。
実践ルール: 測定した集合のすべての読み手が開ける形式を選び、その集合がサポートする機能だけを選ぶ。どの形式もすべての要件を満たさない場合は、テーブルを分割するか、読み手を変更する。測定が対象としていない機能を、読み手に約束してはならない。
本番環境で起こる問題
共有レイクハウスにおけるフォーマット障害の大半は、フォーマット自体のバグではなく、書き込み側が検証していないツールに起因する。ここで挙げる障害はいずれも、前の節で計測または引用したものであり、読者自身のテーブルでも確認できる。
ベンダーの主張による選定。 サポートページが記述しているのは単一のエンジンであり、そのバージョンは読者のものと異なることが多い。何をテストすべきかを知るために使うものであり、答えとして使うものではない。主張は自分の固定されたバージョンに照らして確認する。
単一のエンジンだけのテスト。 あるライブラリで書き込んだテーブルを、同じ機能に対応していない別のライブラリが読み込むことがある。書き込みは一方のツールでは成功し、障害は二つ目のツールがテーブルを開いたときに現れる。最初の書き込みの前に、セットに含まれる各ツールで読み取りチェックを実行する。
リーダーが実装していない機能。 削除ベクトルの設定は、テーブルにリーダー機能を追加し、プロトコルはリーダーにその実装を求める。セットに含まれないリーダーは、テーブルを開いてもその機能で失敗することがある。これは、後のクエリエラーからではなく、機能チェックの例が出力するプロトコルレコードから把握する。
何も起こらない名前変更。 これらの固定されたバージョンでは、deltalake の set_column_metadata 呼び出しはエラーを出さずに戻り、バージョンも進むが、列名は変わらない。第3章がこの落とし穴を示している。確認方法は、変更後に列名を読み取ることである。
誤った順序でのアップグレード。 リーダーより先に書き込み側を更新すると、リーダーが開けないテーブルができることがあり、最初の兆候は別チームのジョブでの読み取り失敗として現れる。チェックリストの順序に従えば、各段階ですべてのリーダーがテーブルを開ける状態が保たれる。
書き込みによるテーブルの判断。 書き込みが成功したことは、書き込み側がファイルを生成できることを示すにすぎない。別のツールがそれを読み取れることまでは示さない。本章の削除ベクトルのチェックが、書き込み、削除を行い、そのうえでリーダーの機能を数えるのは、まさにこのためである。
DuckLake の削除での行数カウント。 DuckLake の既定のインライン化では、数行の小さな削除は削除ファイルを書き込まず、インライン化を無効にした同じ削除では書き込まれる。行数を数えるチェックは、どちらの場合でも削除が成功したと判定する。DuckLake の削除の例のように、削除ファイルも数える。
DuckDB に連動して変わるカタログバージョン。 これらの固定されたバージョンでは、DuckLake カタログはバージョン 1.1 を報告し、それを開く拡張機能はビルド 417a9117f5 を報告する。DuckLake のドキュメントは、バージョン 1.1 が必要とする DuckDB のリリースを示している(DuckLake docs)。それより古い DuckDB はそのカタログを開けない可能性があり、アップグレードによって、変更していないリーダーが動かなくなることがある。
実践ルール: 書き込み、アップグレード、ベンダーの主張への依存のいずれの前にも、すべてのリーダーをそれぞれの固定されたバージョンで計測する。書き込み側やカタログをアップグレードするときは、すべてのリーダーがその結果を開けるまで、古いリリースを残しておく。
本章で下した決定
- これらのピン留めバージョンでは、Iceberg フォーマットバージョン 2 と pyiceberg の組み合わせを推奨する。フォーマットバージョン 3 は、どの読み手に対しても保証せず、それが変わる時期も定めない。決めるのはピン留めであり、それを示すのは測定である。
- 対応表は、これらのピン留めバージョンで測定した結果として示す。各セルは、例または引用した出典を指す。
- 削除ベクターは、検証した範囲の外にいる読み手が開くテーブルには入れない。
- これらのピン留めバージョンでは、deltalake のテーブルでのリネームを保証しない。
- DuckLake では、行数だけでなく削除ファイルも数える。
- 測定していない機能は、未対応として扱う。本章の失敗はすべて、誰かが対応していると思い込んだ機能から生じたためである。
- DuckLake のカタログバージョンは、拡張機能のバージョンとは別に記す。カタログバージョンは、どの読み手がそのカタログを開けるかを決める。拡張機能のバージョンは DuckDB に従う。
- ベンダーのサポートページではなく、測定した対応表を選んだ。何が開けるかを決めるのは、ピン留めしたバージョンだからである。
- Iceberg フォーマットバージョン 2 を既定とするのは判断であり、判断であると明記している。その根拠となる測定は各例にあり、再実行すべき部分でもある。
- 本書は、DuckDB の
delta拡張もiceberg拡張も実行しない。本書の例は、実行時に何もインストールせず、各フォーマット自身のライブラリを使う。DuckDB のdelta拡張は、そのドキュメントが説明するとおり、Delta Lake テーブルを書き込める。
この版における本章
第2026.11.10版2026年11月20日時点で例が通過この章の5 例件のうち5件が合格
英語版の書籍(版2026.11.10)から翻訳した。