最初のテーブルを端から端まで作る

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

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

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

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

この章を終えると、行のバッチをテーブルにコミットし、そのテーブルを DuckDB で読み戻し、合計値を確認できるようになる。本書の対象読者は、SQL と Python を書き、レイクハウスのテーブルをどのように保存し、変更し、整理し、共有し、形式間で移すかを決めなければならない、データエンジニアとアナリティクスエンジニアである。本書は一つの成果物を作る。pageviews テーブルである。このテーブルを保存し、変更し、以前のスナップショット時点のものとして読み、整理し、カタログに登録し、形式間で移す。

フォルダーに置かれた 6 時間分の Wikimedia ページビューは、まだテーブルではない。フォルダーは、どのファイルがテーブルに属するかを示さない。また、途中で止まったロードは、ほかのファイルと見分けがつかないファイルを残す。本書で作るテーブルは時間単位である。各行は、ある言語版で 1 件の公開 Wikipedia 記事が 1 時間に何回閲覧されたかを表す。これを pageviews テーブルと呼ぶ。

この章では、このテーブルの粗い版を作る。テーブルを 3 つの形式(Apache Iceberg、Delta Lake、DuckLake)で書き、それぞれを DuckDB に読み戻して、合計値を比較する。以降の各章は、一つずつ手順を確かなものにする。

  • 第 2 章では、以前のスナップショット時点のテーブルを読む。
  • 第 3 章では、ファイルを書き換えずに列を追加し、名前を変更する。
  • 第 4 章では、古いファイルを書き換えずにパーティショニングを変更する。
  • 第 5 章では、削除、更新、マージで行を訂正する。
  • 第 6 章では、時間単位の追記で残る小さなファイルをコンパクションする。
  • 第 7 章では、スナップショットを期限切れにし、どのスナップショットからも到達できないファイルを削除する。
  • 第 8 章では、テーブルをカタログに登録し、DuckDB からクエリする。
  • 第 9 章では、テーブルを形式間で移し、コピーを検証する。
  • 第 10 章では、使用するツールが対応している内容から形式を選ぶ。

読者は SQL、Python、Parquet を知っており、パーティションが何かも知っているものとする。この章ではそれらを説明しない。

pageviews テーブルの行は、2024 年 6 月 3 日の 6 時間分、すなわち UTC の 00:00 から 05:59 までを対象とする。行は Wikimedia ページビューダンプに由来し、これは Wikimedia プロジェクトが CC0 で公開している。本書では、特別ページを除いたうえで、英語版、ドイツ語版、フランス語版、日本語版について、各時間の閲覧数上位 500 タイトルを使う。日付は固定されており、過去のものであるため、その日のダンプは変わらず、リポジトリ内のデータが古くなることはない。出典、ライセンス、正確な抽出条件は、data フォルダーの READMEに記載している。

このデータは意図的に整っていない。タイトルにはアンダースコアや非ラテン文字が含まれ、カウントには偏りがある。00 時の先頭タイトルの閲覧数は、500 位のタイトルよりはるかに多い。data フォルダーの READMEに記録されているとおり、抽出したすべての行で response_bytes は 0 である。本書はこの列を抽出結果のまま残すので、全体を通して 0 になる。テーブル形式はこうした値をそのまま保存しなければならないため、これらの値はデータに残している。

テーブルフォーマットがファイルに加えるもの

最終変更:版2026.11.10

フォルダを読むものは、そのフォルダにあるすべてのファイルを目にする。テーブルフォーマットはこれにメタデータで答える。テーブルのメタデータとは、テーブルのスキーマと、履歴の各時点でそのテーブルを構成するデータファイルを記録したものである。テーブルへの変更はコミットであり、コミットは新しいメタデータを一度の操作で書き込む。この操作が、テーブルをある状態から次の状態へ移す唯一の変更である。

テーブルフォーマットごとに、メタデータも、これらの概念を指す用語も異なる。Iceberg はコミット後の状態をスナップショットと呼ぶ。Delta Lake はバージョンに番号を振る。DuckLake はスナップショットをカタログファイルに記録する。この章では三つすべてに書き込むので、同じ行をそれぞれのフォーマットで確認できる。

メタデータの置き場所も異なる。Iceberg のテーブルは、現在のスナップショットを指すメタデータファイルを保持する。pyiceberg が書き込むフォーマットバージョン 2 では、各スナップショットがマニフェストリストを指し、マニフェストリストがマニフェストを指し、各マニフェストがデータファイルをその統計とともに指す。これらの各層は Iceberg 仕様が定義している。Delta Lake のテーブルは、データの隣にある _delta_log フォルダに、順序づけられたコミットファイルのログを保持する。これは Delta Lake プロトコルが述べているとおりである。DuckLake のテーブルは、アタッチするカタログファイルにメタデータを保持し、データファイルをそのファイルの隣のフォルダに書き込む。

6 時間分のデータを 1 時間ずつ、三つのフォーマットすべてに書き込み、そのあと各テーブルを読み戻して合計を比較する。

rough-lakehouse.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""Load six hours into Iceberg, Delta Lake and DuckLake, then read each table back.The rows and views lines print each format's totals, and the assert after them checks that the three agree.The titles at the end come from the Iceberg table alone."""from lib.lakehouse import (    format_report,    load_three_formats,    new_warehouse,    print_rows,    safe_error,    sql_rows,    scan_arrow,)# page_title breaks ties in views, so titles with equal views always print in the same order.TOP_THREE = """    SELECT sum(views) AS views, page_title FROM pageviews    GROUP BY page_title ORDER BY views DESC, page_title LIMIT 3"""def main():    try:        with new_warehouse() as wh:            # range(6) is hours 0 to 5, the six hours of the cut, one commit per hour in each format.            iceberg, delta_path, lake = load_three_formats(wh, range(6))            report = format_report(wh, iceberg, delta_path, lake)            for name, (rows, views, files) in report.items():                print(f"{name} rows: {rows}")                print(f"{name} views: {views}")                print(f"{name} data files: {files}")            # A set of (rows, views) pairs has one entry only when all three formats agree.            totals = {(rows, views) for rows, views, _ in report.values()}            assert len(totals) == 1, "the three formats disagree on rows or views"            print("top three page titles over six hours (views, page_title):")            # pageviews names the Arrow table for the SQL; keep_order prints the rows in the SQL's order, not re-sorted.            print_rows(sql_rows(wh.con, TOP_THREE, keep_order=True, pageviews=scan_arrow(iceberg)), keep_order=True)    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
出力python rough-lakehouse.py
iceberg rows: 2999
iceberg views: 1807299
iceberg data files: 6
delta rows: 2999
delta views: 1807299
delta data files: 6
ducklake rows: 2999
ducklake views: 1807299
ducklake data files: 6
top three page titles over six hours (views, page_title):
399885	Main_Page
102089	メインページ
54796	Wikipedia:Hauptseite

三つのフォーマットは同じ行数と同じ閲覧数の合計を報告し、どれも 1 時間につき 1 つのデータファイルを書き込んだ。

  • Iceberg: 2999 行、閲覧数 1807299、データファイル 6 個。
  • Delta Lake: 2999 行、閲覧数 1807299、データファイル 6 個。
  • DuckLake: 2999 行、閲覧数 1807299、データファイル 6 個。

三つのフォーマットの行数または閲覧数の合計が一つでも食い違えば、assert が実行を止める。出力はそのあと、6 時間で最も閲覧された 3 つのタイトルを、Iceberg のテーブルだけから読んで示す。それは Main_Page、メインページ、Wikipedia:Hauptseite で、英語版、日本語版、ドイツ語版のメインページである。

出力にはスナップショット ID もバージョン番号もファイル名も含まれない。これらは実行ごとに変わるからである。スナップショットがどのようにラベル付けされるかは、1 時間ごとの追記で示す。

DuckLake では、手元のマシンで追加の手順が一つ必要になる。DuckDB で INSTALL ducklake を実行し、続けて LOAD ducklake を実行する。本書の実行では、代わりにリポジトリ内のファイルから DuckDB 公式の署名付き ducklake 拡張のコピーを読み込むので、ネットワーク接続なしで動く。DuckLake にはファイル数に影響するインライン化の既定値もある。既定では、10 行以下の挿入を Parquet ファイルではなくカタログに保持する。DuckLake のデータインライン化のページは既定値を次のように述べている。「Data inlining is enabled by default with a row limit of 10.」この例では上限を 0 に設定している。そのため挿入のたびにファイルが書き込まれ、ファイル数はどの章でも同じ意味を持つ。

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

One load loop, three commit styles

最終変更:版2026.11.7

The helper load_three_formats() in examples/lib/lakehouse.py holds the loop that rough-lakehouse calls. The loop writes each hour to all three tables, and each line that writes is one commit in one format:

for hour in hours:
    rows = read_cut_hour(hour)
    iceberg.append(rows)
    write_deltalake(delta_path, rows, mode="append")
    lake.register("hour", rows)
    lake.execute(f"INSERT INTO {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SELECT * FROM hour")
    lake.unregister("hour")

read_cut_hour returns one hour of the cut as an Arrow table, with the same five columns in every format. The Iceberg append creates a snapshot. The Delta append creates a new version, and it creates the table on the first call, when the path does not yet hold one. The DuckLake insert writes a Parquet file and records a snapshot in the catalog file. The three calls differ, and the table each one writes is the same six hours of rows. The loop itself checks nothing. It runs the six loads in order and stops if one of them raises an error. The checks come after all six hours are in, when rough-lakehouse reads back each format's totals and compares them.

コミットはテーブルのファイルを指定する

最終変更:版2026.11.10

Apache Iceberg table specは、スナップショットを、ある時点におけるテーブルの状態として定義している。リーダーはスナップショットを使って、テーブル内のすべてのデータファイルを見つける。したがってスナップショットは二つの役割を持つ。一つは、その時点でテーブルが保持するデータファイルを指定すること、もう一つは、そのスナップショットを作った操作を記録することである。仕様には操作の種類が列挙されている。追記の場合、操作はappendであり、Icebergの仕様はこれを「Only data files were added and no files were removed.」(データファイルが追加されただけで、削除されたファイルはない)と説明している。

pageviewsテーブルで具体的に確認しよう。ロードした1時間分が一つのデータファイルになり、1回のロードが1回のコミットになる。最初のコミットの後、テーブルが保持するのは00時のファイルだけである。2回目のコミットの後は2ファイルになり、以降も同様に増えていく。データファイルが編集されることはない。コミットはファイルを追加し、新しいスナップショットは、そのコミットの後にテーブルが保持するファイルを指定する。

テーブルのデータファイル数は、フォルダではなくスナップショットから得られる。rough-lakehouseは、各フォーマットがそのテーブルについて報告するデータファイル数を表示する。この数はテーブルが自身で保持していると述べる数であり、フォルダの一覧は異なる数を示すことがある。

実践ルール: テーブルが何を保持しているかは、フォルダを一覧するのではなく、現在のスナップショットを通じてテーブルに問い合わせる。フォルダには書き込み側が置いたすべてのファイルが入っているが、そのうちテーブルが読むのはどのファイルかを示すのはスナップショットである。

各フォーマットを Python ライブラリで教える理由

最終変更:版2026.11.10

rough-lakehouse の例では、フォーマットごとに異なるライブラリで書き込みを行った。本節ではその理由を述べる。本書は Apache Iceberg と Delta Lake を、読者が実際に実行に用いる Python ライブラリで書き込む。使用するのは、バージョン 0.12.0 の pyiceberg と、バージョン 1.6.6 の deltalake である。バージョン 2.0.0 の DuckDB は、これらのライブラリが書き込んだものを読み取る。Iceberg テーブルは スキャン から Arrow テーブルとして読み取り、Delta テーブルは deltalake が実行するクエリから Arrow テーブルとして読み取る。DuckLake は例外である。DuckDB は ducklake 拡張を通じて DuckLake を自ら実行し、テーブルのカタログファイルをアタッチする。本書は DuckDB の iceberg 拡張も delta 拡張も使用せず、これらを実行する例もない。

フォーマット 書き込み側 DuckDB が読み取る経路
Apache Iceberg pyiceberg、0.12.0 スキャンから得た Arrow テーブル
Delta Lake deltalake、1.6.6 deltalake の QueryBuilder から得た Arrow テーブル
DuckLake DuckDB 2.0.0 上の DuckDB の ducklake 拡張 カタログファイルへの ATTACH

この選択にはコストがある。Spark や Trino で Iceberg を実行する読者は、そちらでフォーマットのより多くの部分に触れることになり、本書が扱わない機能にも出会う。本書はそれらの箇所を示すにとどめ、それらのエンジンについては教えない。得られる利点は、構成要素が少なくなることである。各フォーマットは自身のライブラリで書き込まれ、DuckDB がその出力を読み取る。各ライブラリのバージョンは固定されており、各章が示すのはフォーマット仕様のバージョンではなく、固定したライブラリのバージョンである。固定の記述は examples/requirements.txt にあり、このファイルは全パッケージを 1 行につき 1 つの厳密なバージョンで列挙している。このファイルからインストールした読者は、本章が実行時に用いたライブラリをそのまま得られる。Python のバージョンは pip が選択しないため、examples/.python-version が指定するバージョンを使用すること。

実践ルール: 各テーブルの書き込みと読み取りは、バージョンを固定したライブラリで行い、読み取りにどのバージョンを使っているかを明記する。エンジン自身の拡張に手を伸ばすのは、ライブラリでは実現できないことを計測で確かめた後に限る。

3時間分をテーブルに取り込む

最終変更:版2026.11.7

rough-lakehouseの例ではループ全体を示した。この節ではその速度を落とし、1つのテーブルに絞って見ていく。バッチの取り込みは2つの手順から成る。テーブルを作成し、その後、各バッチをそのテーブルにコミットする。pageviews テーブルには、まず 00、01、02 の各時間帯を取り込むので、1時間分が1回のコミットになる。その例では、最初の3時間分の後に、03 から 05 の時間帯を同じ方法で読み込む。この節の残りでは、示せる内容が最も多いので、Iceberg テーブルだけを扱う。

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

Create the table in a catalog

最終変更:版2026.11.10

An Iceberg table needs a catalog, which is the registry that maps a table name to the table's current metadata. A Delta Lake table is found by its path, with no catalog, and a DuckLake table lives in its catalog file. The book uses pyiceberg's SQL catalog on SQLite for the Iceberg table. The catalog is one file, and the table's data files go in a warehouse folder beside it. The catalog holds pointers and metadata, not rows. Inside the catalog file, a table name such as wiki.pageviews_hourly maps to the location of the table's current metadata file. A commit writes a new metadata file and moves that mapping, so anyone who asks the catalog for the table gets the metadata that the most recent commit wrote. The helper new_warehouse() in examples/lib/lakehouse.py makes a temporary catalog and warehouse for each run, and removes them when the run ends. Because SQLite is a file and needs no server, the whole catalog runs on a laptop with the network off.

The table has five columns, and its schema says what each one holds:

Schema(
    NestedField(1, "hour_utc", TimestampType(), required=False),
    NestedField(2, "domain_code", StringType(), required=False),
    NestedField(3, "page_title", StringType(), required=False),
    NestedField(4, "views", LongType(), required=False),
    NestedField(5, "response_bytes", LongType(), required=False),
)

The hour_utc column holds a timestamp without a time zone, in UTC, and the two counts are 64-bit integers. The helper create_iceberg_table() creates the table in the catalog, unpartitioned. Chapter 4 adds a partition spec to it.

Working rule: Write the schema out in code, with the type each column really has, before the first commit. The types are then decided on purpose, and not by whichever batch happens to arrive first.

各時間帯をコミットとして追記する

最終変更:版2026.11.10

追記は1回のコミットである。以下では、pyiceberg がテーブルを作成し、00時、01時、02時の順に追記し、続いてスナップショットをコミット順に、その操作種別と各コミットが追加した行数とともに一覧表示する。

append-hours.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""Create the Iceberg table, append hours 00 to 02 as three commits, then repeat hour 00.The hour 00 point rests on the `snapshot 1 rows added` and `snapshot 2 rows added` lines, and the repeated-load point on the two `repeat of hour 00` lines."""from lib.lakehouse import (    create_iceberg_table,    iceberg_file_count,    new_warehouse,    read_cut_hour,    safe_error,    scan_arrow,    snapshot_labels,)def main():    try:        with new_warehouse() as wh:            table = create_iceberg_table(wh)            for hour in range(3):                table.append(read_cut_hour(hour))            # pyiceberg returns the snapshots in commit order, which the labels below depend on.            snapshots = table.snapshots()            # Snapshot IDs change from run to run, so each one prints as its position in commit order.            labels = snapshot_labels([snap.snapshot_id for snap in snapshots])            for snap in snapshots:                label = labels[snap.snapshot_id]                print(f"{label} operation: {snap.summary.operation.value}")                # The commit's own summary holds the rows it added, not a count of the whole table.                print(f"{label} rows added: {snap.summary['added-records']}")            print(f"rows in table: {scan_arrow(table).num_rows}")            # Counted from the current snapshot, not from the folder.            print(f"data files: {iceberg_file_count(table)}")            # Hour 00 again.            table.append(read_cut_hour(0))            repeat = table.current_snapshot()            print(f"repeat of hour 00 operation: {repeat.summary.operation.value}")            print(f"repeat of hour 00 rows added: {repeat.summary['added-records']}")            print(f"rows in table after the repeat: {scan_arrow(table).num_rows}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
出力python append-hours.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
rows in table: 1499
data files: 3
repeat of hour 00 operation: append
repeat of hour 00 rows added: 499
rows in table after the repeat: 1998

00時の分は1行少ない。最初のコミットが追加するのは 499 行で、続く2回のコミットはそれぞれ 500 行を追加する。データ README で説明しているとおり、プライバシーチェックによって00時の分から1行が除かれた。3回のコミットの結果、テーブルには 1499 行が残り、データファイルは 3 個、すなわちコミットごとに1ファイルである。

各コミットはサマリも書き込む。pyiceberg はスナップショットをコミット順に返し、操作種別と追加行数はそこから得られる。各コミットの操作種別は append であり、これは仕様が定める追記操作である。スナップショットのサマリは、テーブルが自身のコミットについて記録している情報であるため、件数が合わないときに最初に確認すべき場所となる。

出力されるラベル snapshot 1、snapshot 2、snapshot 3 は、スナップショット ID の代わりである。Iceberg のスナップショット ID は長い整数であり、仕様はその一意性を要求している。pyiceberg はコミット時に ID を選ぶため、実行ごとに値が変わる。各 ID をコミット順の位置に対応づけておけば、出力は毎回同じになる。

実践ルール: 名前を付けられるバッチごとに1回コミットし、次のコミットを行う前に、各コミットが追加した行数をそのソースから期待される件数と照合する。件数の誤りは、そのコミットが最新である間なら追跡しやすく、上にコミットが積み重なると追跡しにくくなる。

DuckDBでテーブルに問い合わせる

最終変更:版2026.11.10

テーブルが用意できたので、次はそれに対して問い合わせを行いたい。DuckDBはSQLを実行するが、Icebergテーブルはそのままではではない DuckDBのテーブルではない。本書では、テーブルの現在のスナップショットを、pyicebergがスキャンの結果として返すArrowテーブルとして読み込み、そのArrowテーブルを pageviews という名前でDuckDBに登録する。DuckDBはその上で通常のSQLを実行する。Icebergの拡張機能は必要としない。スキャンとは、テーブル自身がスナップショットを読み取る処理である。スナップショットが指定するデータファイルを列挙し、それらを読み込み、ファイルに含まれる行だけを返す。DuckDBが見るのはまさにそれらの行であり、スナップショットが指定していない行は一切見えない。

次の例では、新しいテーブルに00時から02時までのデータを追記し、2つの問いを投げる。00時に最も多くの閲覧数を集めたタイトルの上位5件と、3時間分の閲覧数の合計である。さらに、その合計をスキャン自身が与える合計と照合する。

scan-into-duckdb.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 合格
"""Read the current Iceberg snapshot into DuckDB and check the totals.The point that DuckDB received every row rests on the two total views lines, which the assert compares."""from lib.lakehouse import (    create_iceberg_table,    new_warehouse,    print_rows,    read_cut_hour,    safe_error,    scan_arrow,    sql_rows,)def main():    try:        with new_warehouse() as wh:            table = create_iceberg_table(wh)            for hour in range(3):                table.append(read_cut_hour(hour))            # The current snapshot's rows as one Arrow table, sorted by every column.            arrow = scan_arrow(table)            top = sql_rows(                wh.con,                # hour_utc is UTC, so this is hour 00 of 3 June 2024; page_title breaks ties in views.                """                SELECT views, page_title FROM pageviews                WHERE hour_utc = TIMESTAMP '2024-06-03 00:00:00'                ORDER BY views DESC, page_title LIMIT 5                """,                # keep_order returns the rows in the order the SQL sorted them, not sorted again.                keep_order=True,                pageviews=arrow,            )            print("top five pages for hour 00 (views, page_title):")            print_rows(top, keep_order=True)            # One row with one column: the sum.            duckdb_total = sql_rows(wh.con, "SELECT sum(views) FROM pageviews", pageviews=arrow)[0][0]            # A second route to the same total, summed in Python from the scan's own rows.            pyiceberg_total = sum(arrow["views"].to_pylist())            print(f"total views in DuckDB: {duckdb_total}")            print(f"total views in the scan: {pyiceberg_total}")            assert duckdb_total == pyiceberg_total, "DuckDB and the scan disagree on the total"    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
出力python scan-into-duckdb.py
top five pages for hour 00 (views, page_title):
61107	Main_Page
13791	メインページ
9492	Wikipedia:Hauptseite
7511	Wikipédia:Accueil_principal
3781	笹生優花
total views in DuckDB: 899451
total views in the scan: 899451

一覧には、00時の閲覧数が多い上位5件のタイトルが、閲覧数の多い順に並ぶ。同数の場合はタイトルで順位を決める。各行は、閲覧数、タブ、タイトルの順に表示される。DuckDBでの合計は 899451 回の閲覧であり、スキャン自身の合計 899451 と一致している。両者が食い違った場合は、assertが実行を止める。

合計がスキャンの合計と一致することは、スキャンが返したすべての行をDuckDBが受け取ったことを示す。しかし、行そのものの正しさは確認していないし、上位5件を求めるクエリの正しさも確認していない。合計の検査は1行で済むので、クエリを変更するたびに実行する価値がある。行をもとのデータと照合する作業は、後続の章が担う。そこでは、各変更を、その変更の元になったデータと比較する。

実践ルール: IcebergテーブルはスキャンによるArrowテーブルとしてDuckDBに読み込み、合計をスキャン自身の合計と比較して、DuckDBがすべての行を受け取ったことを確認する。そのうえで、各クエリの結果を、比較できる元のデータと照らして検査する。

本番環境で起こる問題

最終変更:版2026.11.10

第1章で示した経路は短く、その中に本番環境で出会う4つの問題が隠れている。

繰り返したロードは同じ行を再び追加する。 仕様がこの操作を定義しているとおり、append は与えられたデータファイルを追加するだけで、何も取り除かない。テーブルの中には、hour 00 の2つ目のコピーを防ぐ仕組みがない。hour 00 の2つ目のコピーを含むコミットは、ほかのコミットと見分けがつかない。append-hours がこれを示している。繰り返されたコミットの操作は append であり、追加される行数は 499 行で最初のコピーと同じ件数である。その後テーブルは 1998 行を保持するが、エラーは出ない。そのロードを一度だけ実行するつもりだったことを示す記録は、実行前に書き留めておいた件数だけである。誤ってロードした行を訂正する方法は第5章で扱う。

フォルダの中身はテーブルの中身より多い。 ウェアハウスのフォルダにあるファイル数は、テーブルのファイル数とは別の問いに答えるものである。フォルダには、書き込み側がそこに置いたすべてのファイルがあり、テーブルが保持するものはスナップショットが定める。フォルダ内の Parquet ファイルを数えるツールは、テーブルが約束していない数を報告する。テーブルがもはや参照しないファイルの扱いは、第6章と第7章で述べる。

スナップショット ID、バージョン、スナップショット番号は、それぞれ種類の異なる数である。 Iceberg の ID は64ビットの値である。Delta Lake のバージョンは、コミット順に0から数える。DuckLake もスナップショットに番号を付け、行を挿入するたびだけでなく、スキーマやテーブルを作成するたびにもスナップショットを記録する。あるフォーマットの番号を保存し、それを別のフォーマットのバージョンとして読むスクリプトは、誤った状態を読むことになる。

DuckLake の小さな挿入はファイルを書き出さない。 既定では、DuckLake は10行以下の挿入をカタログの中に保持する。したがって、小さな挿入の後にファイル数が0になるのは失敗ではなく、想定どおりの結果である。本書の DuckLake の例では、行数の上限を0に設定している。ただし第10章の ducklake-inlined-delete は例外で、既定のままにして、小さな削除が削除ファイルを書き出さないことを示している。挿入を自分のカタログにそのまま写す読者は、先にこの既定値を知っておくべきである。

実践ルール: 各コミットが追加するはずの行数を、そのコミットを作るロードの隣に書き留め、ロードのたびにその件数をコミットのサマリと照合する。テーブルは繰り返されたロードを検査しない。あらかじめ書き留めておいた件数が、それを検査する手段である。

この章で下した決定

最終変更:版2026.11.8
  • この章の例は三つである。 rough-lakehouse は結果の全体を三つの形式で作るため、以降の各章は、読者がすでに実行した結果の一部分だけを変更することになる。残る二つの例である append-hours と scan-into-duckdb は、Iceberg テーブルを一回のコミットずつ組み立て、それを DuckDB で読む。
  • 先に 00 時から 02 時までを扱い、次に 03 時から 05 時までを扱う。 Iceberg の例が取り込むのは三時間分であり、ラフな例が取り込むのは六時間分である。六時間すべてを合計するのは rough-lakehouse だけである。
  • パーティション化しないテーブル。 第 1 章ではパーティション仕様なしでテーブルを作成する。パーティション化は第 4 章で変更する。第 4 章の day 変換と hour 変換には pyiceberg-core が必要なので、このパッケージは pyiceberg と並べてバージョンを固定している。
  • 例ではインライン化を無効にする。 DuckLake の例では DATA_INLINING_ROW_LIMIT を 0 に設定する。これにより、挿入のたびに Parquet ファイルが書き込まれ、本書のどこでファイル数を示しても同じ意味になる。第 10 章の ducklake-inlined-delete は既定値のままにする。その狙いは、小さな削除では削除ファイルが書き込まれないことを示す点にあるためである。
  • Delta テーブルは deltalake の QueryBuilder だけを通して読む。 examples/lib/lakehouse.py にある読み取り用ヘルパーはこの経路を取り、Delta テーブルを読む以降の各章も同じヘルパーを使う。
  • 代用品ではなく実データを使う。 この章の各例は、データの README が説明する、六つの公開ダンプから切り出したデータを読む。この章用に生成したデータは、本書には付属しない。
  • Iceberg カタログには SQLite を使う。 SQLite ファイルはサーバーを必要としないため、Iceberg の例はネットワークを切ったノートパソコンでも動作する。これらの実行では DuckDB の拡張機能の自動ダウンロードも無効にしているので、ネットワークを必要とする実行は、取得を試みずに失敗する。
  • ID の代わりにラベルを使う。 出力に示す snapshot 1、snapshot 2 などは、スナップショット ID の代わりである。これにより、実行のたびに出力が変わることがない。

この版における本章

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

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

この節を引用する

形式

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

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

このページの内容

全10章中の第1章: 最初のテーブルを端から端まで作る

  1. テーブルフォーマットがファイルに加えるもの
  2. One load loop, three commit styles
  3. コミットはテーブルのファイルを指定する
  4. 各フォーマットを Python ライブラリで教える理由
  5. 3時間分をテーブルに取り込む
  6. Create the table in a catalog
  7. 各時間帯をコミットとして追記する
  8. DuckDBでテーブルに問い合わせる
  9. 本番環境で起こる問題
  10. この章で下した決定

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