databricks-iceberg

Databricks 上の Apache Iceberg

Databricks では、Apache Iceberg を使用する方法が複数あります。ネイティブのマネージド Iceberg テーブル、Delta と Iceberg の相互運用を可能にする UniForm、外部エンジンからアクセスするための Iceberg REST Catalog（IRC）です。

---

重要なルール（必ず遵守）

• 必須：Unity Catalog を使用してください。すべての Iceberg 機能には、UC が有効なワークスペースが必要です。
• 禁止：Databricks Runtime（DBR）に Iceberg ライブラリをインストールしないでください（DBR には Iceberg のサポートが組み込まれているため、ライブラリを追加するとバージョンの競合が発生します）。
• 禁止：write.metadata.path または write.metadata.previous-versions-max を設定しないでください。Databricks がメタデータの保存先を自動的に管理するため、上書きすると破損の原因になります。
• 必須：コードを書く前に、ユースケースに適した Iceberg パターンを判断してください。以下の使い分けセクションを参照してください。
• 必須：PARTITIONED BY と CLUSTER BY のどちらを使っても、外部エンジン向けには同じ Iceberg メタデータが生成されることを理解してください。UC はクラスタリングキーに対応するパーティションフィールドを含む Iceberg パーティション仕様を維持します。そのため、IRC 経由で読み取る外部エンジンには、パーティション化された Iceberg テーブルとして表示されます（Hive 形式ではなく、適切な Iceberg パーティションフィールドが設定されます）。これらのフィールドによるプルーニングも可能です。UC 内部では、これらのフィールドがリキッドクラスタリングキーとして使用されます。2 つの構文の違いは次のとおりです。（1）PARTITIONED BY は標準の Iceberg DDL であり、どのエンジンでもテーブルを作成できます。一方、CLUSTER BY は DBR 専用の DDL です。（2）PARTITIONED BY は DV／行追跡のプロパティを自動的に処理しますが、v2 で CLUSTER BY を使用する場合は TBLPROPERTIES を手動で設定する必要があります。
• 禁止：マネージド Iceberg テーブルで PARTITIONED BY を使用する際に、式ベースのパーティション変換（bucket()、years()、months()、days()、hours()）を使用しないでください。プレーンな列参照のみがサポートされています。式による変換はエラーになります。
• 必須：Iceberg v2 テーブルで CLUSTER BY を使用する場合は、削除ベクトルと行追跡を無効にしてください。TBLPROPERTIES に 'delta.enableDeletionVectors' = false と 'delta.enableRowTracking' = false を設定します（Iceberg v3 ではこれらは自動的に処理されます。PARTITIONED BY では v2 と v3 の両方で自動的に処理されます）。

---

主な概念

概念	概要
マネージド Iceberg テーブル	USING ICEBERG を使って作成するネイティブ Iceberg テーブル。Databricks および外部 Iceberg エンジンから完全な読み取り／書き込みが可能です。
外部 Iceberg 読み取り（Uniform）	Iceberg メタデータを自動生成する Delta テーブル。外部からは Iceberg として読み取り、内部では Delta として書き込みます。
互換モード	SDP パイプラインのストリーミングテーブルとマテリアライズドビュー向けの UniForm のバリアントです。
Iceberg REST Catalog（IRC）	Iceberg REST Catalog 仕様を実装した、Unity Catalog 組み込みの REST エンドポイントです。外部エンジン（Spark、PyIceberg、Snowflake）から UC 管理の Iceberg データにアクセスできます。
Iceberg v3	次世代フォーマット（DBR 18 LTS 以降）。削除ベクトル、VARIANT 型、行系列をサポートします。

---

クイックスタート

マネージド Iceberg テーブルを作成する

-- No clustering
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
AS SELECT * FROM raw_events;

-- PARTITIONED BY (recommended for cross-platform): standard Iceberg syntax, works on EMR/OSS Spark/Trino/Flink
-- auto-disables DVs and row tracking — no TBLPROPERTIES needed on v2 or v3
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
PARTITIONED BY (event_date)
AS SELECT * FROM raw_events;

-- CLUSTER BY on Iceberg v2 (DBR-only syntax): must manually disable DVs and row tracking
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
TBLPROPERTIES (
  'delta.enableDeletionVectors' = false,
  'delta.enableRowTracking' = false
)
CLUSTER BY (event_date)
AS SELECT * FROM raw_events;

-- CLUSTER BY on Iceberg v3 (DBR-only syntax): no TBLPROPERTIES needed
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
TBLPROPERTIES ('format-version' = '3')
CLUSTER BY (event_date)
AS SELECT * FROM raw_events;

既存の Delta テーブルで UniForm を有効にする

ALTER TABLE my_catalog.my_schema.customers
SET TBLPROPERTIES (
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

---

読み取り／書き込み機能マトリックス

テーブルの種類	Databricks での読み取り	Databricks での書き込み	外部 IRC からの読み取り	外部 IRC からの書き込み
マネージド Iceberg（USING ICEBERG）	はい	はい	はい	はい
Delta + UniForm	はい（Delta として）	はい（Delta として）	はい（Iceberg として）	いいえ
Delta + 互換モード	はい（Delta として）	はい	はい（Iceberg として）	いいえ

---

参照ファイル

ファイル	概要	キーワード
references/1-managed-iceberg-tables.md	ネイティブ Iceberg テーブルの作成と管理 — DDL、DML、Liquid Clustering、Predictive Optimization、Iceberg v3、制限事項	CREATE TABLE USING ICEBERG, CTAS, MERGE, タイムトラベル, 削除ベクトル, VARIANT
references/2-uniform-and-compatibility.md	Delta テーブルを Iceberg として読み取り可能にする — 通常のテーブル向け UniForm、ストリーミングテーブルと MV 向け Compatibility Mode	UniForm, universalFormat, Compatibility Mode, ストリーミングテーブル, マテリアライズドビュー, SDP
references/3-iceberg-rest-catalog.md	IRC エンドポイントを介して Databricks テーブルを外部エンジンに公開 — 認証、認証情報の提供、IP アクセスリスト	IRC, REST Catalog, 認証情報の提供, EXTERNAL USE SCHEMA, PAT, OAuth
references/4-snowflake-interop.md	Snowflake と Databricks の双方向連携 — カタログ統合、外部カタログ、提供される認証情報	Snowflake, カタログ統合, 外部ボリューム, 提供される認証情報, REFRESH_INTERVAL_SECONDS
references/5-external-engine-interop.md	IRC を介した PyIceberg、OSS Spark、AWS EMR、Apache Flink、Kafka Connect の接続	PyIceberg, OSS Spark, EMR, Flink, Kafka Connect, pyiceberg.yaml

---

使用する場面

• 新しい Iceberg テーブルを作成する → references/1-managed-iceberg-tables.md
• 既存の Delta テーブルを Iceberg として読み取り可能にする → references/2-uniform-and-compatibility.md
• ストリーミングテーブルまたは MV を Iceberg として読み取り可能にする → references/2-uniform-and-compatibility.md（Compatibility Mode のセクション）
• Managed Iceberg、UniForm、Compatibility Mode のどれを選ぶか → references/2-uniform-and-compatibility.md の判断表
• REST API を介して Databricks テーブルを外部エンジンに公開する → references/3-iceberg-rest-catalog.md
• Databricks と Snowflake を連携する（どちらの方向でも） → references/4-snowflake-interop.md
• PyIceberg、OSS Spark、Flink、EMR、Kafka を接続する → references/5-external-engine-interop.md

---

よくある問題

問題	解決策
変更データフィード（CDF）がない	マネージド Iceberg テーブルでは CDF はサポートされていません。CDF が必要な場合は、Delta + UniForm を使用してください。
UniForm の非同期処理による遅延	Iceberg メタデータの生成は非同期です。書き込み後、外部エンジンが最新データを参照できるようになるまで、わずかな遅延が発生する場合があります。DESCRIBE EXTENDED table_name でステータスを確認してください。
圧縮コーデックの変更	マネージド Iceberg テーブルでは、デフォルトで zstd 圧縮が使用されます（snappy ではありません）。zstd をサポートしていない古い Iceberg リーダーではエラーになります。リーダーとの互換性を確認するか、write.parquet.compression-codec を snappy に設定してください。
Snowflake の 1000 コミット制限	Snowflake の Iceberg カタログ統合で参照できるのは、直近の Iceberg コミット 1000 件のみです。書き込み頻度が高い場合はメタデータをコンパクションしてください。そうしないと、Snowflake から古いデータを参照できなくなります。
UniForm での削除ベクトル	UniForm を使用するには、削除ベクトルを無効にする必要があります（delta.enableDeletionVectors = false）。テーブルで削除ベクトルが有効になっている場合は、UniForm を有効にする前に無効にしてください。
Iceberg ではシャロークローンを使用できない	Iceberg テーブルでは SHALLOW CLONE はサポートされていません。代わりに DEEP CLONE または CREATE TABLE ... AS SELECT を使用してください。
外部エンジンとのバージョン不一致	外部エンジンで、テーブルのフォーマットバージョンと互換性のある Iceberg ライブラリのバージョンが使用されていることを確認してください。Iceberg v3 テーブルには、Iceberg ライブラリ 1.9.0 以降が必要です。

---

関連スキル

• databricks-unity-catalog — カタログ／スキーマ管理、ガバナンス、システムテーブル
• databricks-pipelines — SDP パイプライン（ストリーミングテーブル、Compatibility Mode を使用したマテリアライズドビュー）
• databricks-python-sdk — Databricks の操作に使用する Python SDK と REST API
• databricks-dbsql — SQL ウェアハウスの機能、クエリパターン

---

リソース

• Iceberg 概要 — Databricks における Iceberg のメインハブ
• UniForm — Delta Universal Format
• Iceberg REST Catalog — IRC エンドポイントと外部エンジンからのアクセス
• Compatibility Mode — ストリーミングテーブルと MV 向けの UniForm
• Iceberg v3 — 次世代フォーマットの機能
• Foreign Tables — 外部カタログデータの読み取り