Iceberg クライアントを使用して Delta テーブルを読み取る

2025-05-08

この記事では、Azure Databricks の Delta Lake に保存されているテーブルで Iceberg 読み取りを有効にする方法について詳しく説明します。この機能を使用するには、Databricks Runtime 14.3 LTS 以降が必要です。

メモ

これは以前 Delta Lake Universal Format (UniForm) と呼ばれていた機能です。

Unity Catalog が Iceberg カタログとして機能するように外部接続を構成できます。 Apache Iceberg クライアントからの Azure Databricks テーブルへのアクセスに関するページを参照してください。

Apache Iceberg のデータ読み込み (UniForm) のしくみはどのように機能しますか？

Delta Lake と Apache Iceberg はどちらも Parquet データファイルとメタデータレイヤーで構成されます。 Iceberg 読み取りを有効にすると、データを書き換えずに Iceberg メタデータを非同期的に自動生成するようにテーブルが構成され、Iceberg クライアントは Azure Databricks によって書き込まれた Delta テーブルを読み取れるようになります。データファイルの 1 つのコピーで複数の形式に対応できます。

重要

Iceberg 読み取りが有効になっているテーブルでは、基になる Parquet データファイルの圧縮コーデックとして、Snappy ではなく Zstandard が使用されます。
Iceberg メタデータの生成は、Delta テーブルへのデータの書き込みに使用されるコンピューティングで非同期的に実行されるため、ドライバーリソースの使用量が増える可能性があります。
レガシ UniForm IcebergCompatV1 テーブルの機能のドキュメントについては、「レガシ UniForm IcebergCompatV1」を参照してください。

必要条件

Iceberg 読み取りを有効にするには、次の要件を満たす必要があります。

Delta テーブルが Unity Catalog に登録されている必要があります。また、マネージドテーブルと外部テーブルの両方がサポートされている必要があります。
テーブルで列マッピングが有効になっている必要があります。「Delta Lake の列マッピングを使用して列の名前変更と削除を行う」を参照してください。
Delta テーブルに minReaderVersion>= 2 および minWriterVersion>= 7 が必要です。 Delta Lake の機能の互換性とプロトコルに関する記事を参照してください。
テーブルへの書き込みには、Databricks Runtime 14.3 LTS 以降を使用する必要があります。

メモ

Iceberg 読み取りが有効になっているテーブルで削除ベクトルを有効にすることはできません。

削除ベクトルが有効になっている既存のテーブルで Iceberg 読み取りを有効にしながら、削除ベクトルを無効にして消去するには、REORG を使用します。「REORGを使用して Iceberg 読み取りのサポートを有効化またはアップグレードする」を参照してください。

Iceberg 読み取り (UniForm) を有効にする

重要

Iceberg 読み取りを有効にすると、書き込みプロトコル機能 IcebergCompatV2 がテーブルに追加されます。 Iceberg 読み取りが有効になっているテーブルに書き込めるのは、このテーブル機能をサポートしているクライアントのみです。 Azure Databricks では、有効になっているテーブルに書き込むために Databricks Runtime 14.3 LTS 以降を使用する必要があります。

IcebergCompatV2 は列のマッピングに依存します。テーブルに対して IcebergCompatV2 を有効にした場合、columnMapping テーブル機能を削除することはできません。

delta.universalFormat.enabledFormats テーブルプロパティの設定を解除することで Iceberg 読み取りをオフにすることができます。 Delta Lake リーダーおよびライタープロトコルバージョンへのアップグレードを元に戻すことはできません。

Iceberg 読み取りを有効にするには、次のテーブルプロパティを設定する必要があります。

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

初めて Iceberg 読み取りを有効にすると、非同期的なメタデータの生成が開始されます。外部クライアントが Iceberg を使用してテーブルをクエリする前に、このタスクを完了する必要があります。「Iceberg メタデータの生成状態を確認する」を参照してください。

制限事項の一覧については、「制限事項」を参照してください。

テーブルの作成中に Iceberg 読み取りを有効にする

Iceberg 読み取りを使用するには列マッピングを有効にする必要があり、有効にすると、列マッピングは削除できません。次の例のように、テーブルの作成中に Iceberg 読み取りを有効にすれば、これは自動的に実行されます。

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

既存のテーブルで Iceberg 読み取りを有効にする

Databricks Runtime 15.4 LTS 以降では、次の構文を使用して、既存のテーブルで Iceberg 読み取りを有効化またはアップグレードすることができます。

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

`REORG` を使用して Iceberg 読み取りのサポートを有効化またはアップグレードする

次の例のように、REORG を使用して Iceberg 読み取りを有効にし、基になるデータファイルを書き換えることができます。

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

次のいずれかに該当する場合は、REORG を使用します。

テーブルで削除ベクトルが有効になっている。
以前に UniForm Iceberg の IcebergCompatV1 バージョンを有効化した。
Hive スタイルの Parquet ファイル (アテナや Redshift など) をサポートしていない Iceberg エンジンから読み取る必要があります。

Iceberg メタデータの生成はいつ行われますか?

Azure Databricks は、Delta Lake 書き込みトランザクションが完了した後、メタデータの生成を非同期的にトリガーします。このメタデータ生成プロセスでは、Delta トランザクションを完了したものと同じコンピューティングが使用されます。

メモ

Iceberg メタデータの生成を手動でトリガーすることもできます。「Iceberg メタデータの変換を手動でトリガーする」を参照してください。

メタデータ生成に関わる書き込み遅延を回避するために、頻繁にコミットされる Delta テーブルでは、複数の Delta コミットを Iceberg メタデータへの単一のコミットにグループ化する場合があります。

Delta Lake では、特定のコンピューティングリソースで、1 つのメタデータ生成プロセスのみが進行中であることが保証されます。 2 番目の同時メタデータ生成プロセスをトリガーするコミットは、Delta に正常にコミットしますが、非同期 Iceberg メタデータ生成はトリガーしません。これにより、頻繁にコミットされるワークロード (コミット間の間隔が数秒から数分) のメタデータ生成の連鎖的な遅延が防止されます。

「Delta テーブルと Iceberg テーブルのバージョン」を参照してください。

Delta テーブルと Iceberg テーブルのバージョン

Delta Lake と Iceberg では、テーブルメタデータに保存されているテーブルバージョンまたはタイムスタンプを使用して、タイムトラベルクエリを実行できます。

一般に、Delta テーブルのバージョンは、コミットタイムスタンプまたはバージョン ID のいずれにおいても Iceberg バージョンとは一致しません。特定のバージョンの Iceberg テーブルがどのバージョンの Delta テーブルに対応しているかを確認するには、対応するテーブルのプロパティを使用します。「Iceberg メタデータの生成状態を確認する」を参照してください。

Iceberg メタデータの生成状態を確認する

テーブルで Iceberg 読み取りを有効にすると、メタデータの生成状態を追跡するために、Unity Catalog と Iceberg テーブルのメタデータに次のフィールドが追加されます。

メタデータフィールド	説明
`converted_delta_version`	Iceberg メタデータが正常に生成された Delta テーブルの最新バージョン。
`converted_delta_timestamp`	Iceberg メタデータが正常に生成された最新の Delta コミットのタイムスタンプ。

Azure Databricks では、次のいずれかの方法で、これらのメタデータフィールドを確認できます。

Delta Uniform Iceberg によって返される DESCRIBE EXTENDED table_name セクションの確認。
カタログエクスプローラーでのテーブルメタデータの確認。
REST API を使用したテーブルの取得。

Azure Databricks の外部でテーブルのプロパティを確認する方法については、Iceberg リーダークライアントのドキュメントを参照してください。 OSS Apache Spark の場合は、次の構文を使用してこれらのプロパティを確認できます。

SHOW TBLPROPERTIES <table-name>;

Iceberg メタデータの変換を手動でトリガーする

Delta テーブルの最新バージョンに対して Iceberg メタデータ生成を手動でトリガーできます。この操作は同期的に実行されます。つまり、完了すると、Iceberg で使用できるテーブルコンテンツには、変換プロセスが開始された時に使用可能な Delta テーブルの最新バージョンが反映されます。

この操作は通常の条件下では必要ないと思われますが、次の状況が発生した場合に役立ちます。

メタデータの自動生成が成功する前にクラスターが終了する。
エラーまたはジョブの失敗によってメタデータの生成が中断される。
UniForm での Iceberg メタデータの生成をサポートしていないクライアントによって Delta テーブルへの書き込みが行われる。

Iceberg メタデータの生成を手動でトリガーするには、次の構文を使用します。

MSCK REPAIR TABLE <table-name> SYNC METADATA

REPAIR TABLEを参照してください。

メタデータ JSON パスを使用して Iceberg を読み取る

一部の Iceberg クライアントでは、外部の Iceberg テーブルを登録するために、バージョン管理されたメタデータファイルへのパスを指定する必要があります。 Azure Databricks は、Delta テーブルの新しいバージョンを Iceberg に変換するたびに、新しいメタデータ JSON ファイルを作成します。

Iceberg の構成にメタデータ JSON パスを使用するクライアントには、BigQuery が含まれます。構成の詳細については、Iceberg リーダークライアントのドキュメントを参照してください。

Delta Lake では、次のパターンを使用して、Iceberg メタデータをテーブルディレクトリの下に保存します。

<table-path>/metadata/<version-number>-<uuid>.metadata.json

Azure Databricks では、次のいずれかの方法で、このメタデータの場所を確認できます。

Delta Uniform Iceberg によって返される DESCRIBE EXTENDED table_name セクションの確認。
カタログエクスプローラーでのテーブルメタデータの確認。
REST API での次のコマンドの使用:

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

応答には次の情報が含まれています。

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

重要

パスベースの Iceberg リーダークライアントでは、現在のテーブルバージョンを読み取るために、メタデータ JSON パスを手動で更新およびリフレッシュする必要が生じる場合があります。 VACUUM によって Parquet データファイルが Delta テーブルから削除されるため、古いバージョンを使用して Iceberg テーブルをクエリすると、エラーが発生する場合があります。

制限事項

Iceberg 読み取りが有効になっているすべてのテーブルには、次の制限事項があります。

削除ベクトルが有効になっているテーブルでは、Iceberg 読み取りが機能しません。「削除ベクトルとは」を参照してください。
iceberg メタデータの生成を自動的にトリガーするには、デルタテーブルに (パスではなく) 名前でアクセスする必要があります。
具体化されたビューまたはストリーミングテーブルで Iceberg 読み取りを有効にすることはできません。
Iceberg 読み取りが有効になっている Delta テーブルは、VOID 型をサポートしていません。
Iceberg クライアントのサポートは読み取り専用です。書き込みはサポートされていません。
Azure Databricks による Iceberg 読み取りのサポートに関係なく、Iceberg リーダークライアントには個別の制限がある場合があります。選択したクライアントのドキュメントを参照してください。
Delta Sharing の受信者は、Iceberg 読み取りが有効になっていても、テーブルを Delta としてしか読み取れません。
Iceberg 読み取りで使用される一部の Delta Lake テーブル機能は、一部の Delta Sharing リーダークライアントでサポートされていません。「Delta Sharing とは」を参照してください。

Iceberg 読み取りが有効になっている場合、変更データフィードは、Delta クライアントでは機能しますが、Iceberg ではサポートされていません。