00. 実験のコンセプト

このラボは、Apache Iceberg と Iceberg REST Catalog について文献で読んだことを、実際に動かして確かめるために作りました。姉妹リポジトリの調査報告書で述べている主張のうち、手元で検証できるものをここで検証しています。

なぜ動かして確かめるのか

Iceberg の情報は、次の3つが混同されたまま流通しがちです。

  • 仕様がそう定めていること
  • ある実装がそう振る舞うこと
  • ブログにそう書いてあったこと

この3つは一致しません。たとえばテーブル仕様 v3 は deletion vector を定義していますが、PyIceberg 0.11.1 は v3 を書けません。仕様を読んだだけでは「v3 が使える」と誤解します。逆に、実装を触っただけでは「これは仕様上の制約なのか、この実装の都合なのか」が区別できません。

そこで本ラボでは、仕様の記述を引用し、対応する挙動を実際に走らせ、観測結果を並べるという形をとっています。一致すれば裏が取れたことになり、食い違えば、それ自体が記録すべき事実になります。

何を検証対象にしたか

検証したのは、次の観点です。

  • 既定値 — 新規テーブルの format-version、削除モードなど。「既定でどうなるか」は設計判断に直結しますが、文献では曖昧なまま語られがちです。
  • メタデータ構造 — 三層構造を実際に開いて、どこに何が入っているかを見ます。
  • 進化の仕組み — スキーマ進化とパーティション進化が、既存データを書き換えずに成立する仕組みを確認します。
  • REST プロトコル — コミットがどういう HTTP のやりとりで実現されているか。特に楽観的並行制御の実際の挙動。
  • 実装の制約 — PyIceberg で何ができないか。これは「できること」より重要な場合があります。

検証しなかったこと

範囲を明示しておきます。以下は本ラボでは扱っていません。

対象 理由
性能・スケール ローカルの単一ノード環境では、意味のある測定ができません
Spark / Flink / Trino との連携 環境が大きくなりすぎるため。compaction や MERGE INTO はここでは試せません
本番相当の認証（OIDC / 外部 IdP） 学習用に /v1/oauth/tokens を使っています。これは仕様上、削除予定のエンドポイントです
永続化 Polaris のメタデータは in-memory です。docker compose down で消えます
マルチテナント・権限設計 principal とロールは動かすための最小構成のみです

つまり本ラボは、仕様と実装の挙動を確かめるためのものであり、本番構成の雛形ではありません。

実験の構成

サンプルは、下の層から順に理解できるように並べています。

flowchart TD
    A["10. 接続とケイパビリティ<br/>GET /v1/config を見る"] --> B["11. 基本 CRUD<br/>既定値を確かめる"]
    B --> C["12. スキーマ進化<br/>field ID の役割"]
    B --> D["13. パーティション進化<br/>hidden partitioning"]
    C --> E["15. メタデータ三層構造<br/>実物を開く"]
    D --> E
    B --> F["14. タイムトラベル<br/>スナップショットと参照"]
    F --> E
    E --> G["16. REST API を直接叩く<br/>コミットプロトコルと 409"]
    G --> H["17. 実装の制約<br/>できないことを確かめる"]

前半（10〜13）は Iceberg のテーブルとしての振る舞い、中盤（14〜15）はそれを支えるメタデータ構造、後半（16〜17）はカタログのプロトコルと実装の限界、という順です。

検証環境

項目 値
検証基準日 2026-07-17
Apache Iceberg 1.11.0
PyIceberg 0.11.1
Apache Polaris 1.6.0
ストレージ RustFS 1.0.0-beta.8（S3 互換）
実行環境 Docker 29.6.1 / Compose v5.3.0 / Python 3.10 / WSL2

構成の詳細と、なぜこの組み合わせを選んだかは 01. 環境構成 に書いています。

結果の読み方

各サンプルのドキュメントは、次の順で書いています。

  1. 確かめたいこと — 何を検証する実験か
  2. 背景 — 前提となる概念と仕様の記述
  3. 処理の流れ — コードが実際に何をしているか
  4. 実測結果 — 実行して観測されたもの
  5. ここから分かること — 結論

「実測結果」に載せている出力は、検証環境で実際に実行したものをそのまま転記しています。スナップショット ID のように実行ごとに変わる値も、実物を載せています。

実験を通して分かったことは 90. 分かったことのまとめ に集約しています。