Iceberg REST Lab

警告この文書の位置づけ

これは著者による個人的な実験記録であり、本番環境での利用を想定して書かれたものではありません。

  • 特定時点（2026年7月）のスナップショットであり、内容は急速に陳腐化します
  • ローカルの単一ノード環境での確認であり、性能やスケールについては何も言えません
  • 本番システムの設計・構築の根拠として、そのまま用いないでください。 判断に使う数値・バージョン・仕様は、必ず引用元の一次情報で確認してください
  • 記述の誤りによって生じた結果について、著者は責任を負いません

技術的な議論のたたき台や、自分で試すときの出発点として使っていただくことを想定しています。

Apache Polaris と PyIceberg を使い、Iceberg REST Catalog をローカルで動かして文献で読んだことを実際に確かめた記録です。

Version: 2026-07-18 / 検証基準日: 2026-07-17 / 対象: Apache Iceberg 1.11.0 / PyIceberg 0.11.1 / Apache Polaris 1.6.0

Version はこのページを更新した日付、検証基準日は実際に動かして確認した時点です。Iceberg 周辺は変化が速いため、検証基準日から離れるほど内容は古くなります。

姉妹リポジトリの調査報告書が文献調査、こちらがその実地検証にあたります。

何をした記録か

Iceberg の情報は「仕様がそう定めている」「ある実装がそう振る舞う」「ブログにそう書いてあった」が混同されたまま流通しがちです。この 3 つは一致しません。

そこで、仕様の記述を引用し、対応する挙動を実際に走らせ、観測結果を並べるという形で確かめました。詳しくは 00. 実験のコンセプト を参照してください。

docker compose down -v でまっさらにした状態から、サンプル 8 本すべての完走を確認しています（Docker 29.6.1 / Compose v5.3.0 / Python 3.10 / WSL2）。

目次

実験の前提

# ドキュメント 内容
00 実験のコンセプト 何を検証し、何を検証していないか
01 環境構成と起動処理 4 コンテナの構成、ブートストラップが実際にやっていること

実験

# ドキュメント 対応するサンプル
10 接続とケイパビリティ確認 samples/00_connect.py
11 基本的な CRUD と既定値 samples/01_basic_crud.py
12 スキーマ進化と field ID samples/02_schema_evolution.py
13 パーティション進化と hidden partitioning samples/03_partition_evolution.py
14 タイムトラベルと branch / tag samples/04_time_travel.py
15 メタデータ三層構造を覗く samples/05_metadata.py
16 REST API を直接叩く samples/06_rest_api_raw.py
17 PyIceberg の制約を実証する samples/07_pitfalls.py

まとめ

# ドキュメント 内容
90 分かったこと 実験を通して確認できたことの集約

自分で動かす

git clone https://github.com/dobachi/iceberg-rest-lab.git
cd iceberg-rest-lab

# 1. 環境を起動（初回はイメージ取得で数分かかります）
make up

# 2. 表示された CLIENT_ID / CLIENT_SECRET を .env に書く
cp .env.example .env
$EDITOR .env

# 3. Python 依存を入れる
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 4. サンプルを動かす
make sample

必要なもの: Docker（compose v2）、Python 3.10 以上。

手順の詳細と、つまずきやすい点は 01. 環境構成 にまとめています。

ライセンス

Copyright (c) 2026 dobachi

対象 ライセンス
コード（compose.yaml / scripts/ / samples/ / Makefile） Apache License 2.0
ドキュメント（docs/ / README.md） CC BY 4.0

compose.yaml と scripts/bootstrap.sh は Apache Polaris（Apache-2.0）公式 guides の派生物です。加えた変更は NOTICE に記載しています。

ドキュメント中の引用部分の権利は、それぞれの権利者に帰属します。