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

Deltaユニバーサルフォーマット (UniForm) を使用すると、Iceberg リーダークライアントでDeltaテーブルを読み取ることができます。この機能には Databricks Runtime 14.3 LTS 以降が必要です。

重要

従来の UniForm IcebergCompatV1テーブル機能のドキュメントについては、「Legacy UniForm IcebergCompatV1」を参照してください。

UniForm は、 Delta Lake と Iceberg の両方が Parquet データファイルとメタデータレイヤーで構成されているという事実を利用しています。 UniForm は、データを書き換えることなく Iceberg メタデータを非同期的に自動的に生成するため、Iceberg クライアントは Delta テーブルを Iceberg テーブルであるかのように読み取ることができます。データファイルの 1 つのコピーが両方の形式に対応します。

外部接続を構成して、 Unity Catalog を Iceberg カタログとして機能させることができます。「 Unity Catalog Iceberg カタログエンドポイントを使用した読み取り」を参照してください。

UniForm は、基盤となる Parquet データファイルの圧縮コーデックとして、snappy ではなく zstd を使用します。

注

UniForm メタデータの生成は、Delta テーブルにデータを書き込むために使用されるコンピュートで非同期的に実行されるため、ドライバーのリソース使用量が増加する可能性があります。

要件

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

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

注

UniForm が有効になっているテーブルでは削除を有効にすることはできません。削除が有効になっている既存のテーブルで UniForm を有効にすると、UniForm は削除を無効にして削除し、必要に応じてデータファイルを書き換えます。

ユニフォーム Delta を有効にする

重要

Delta UniForm を有効にすると、書き込みプロトコル機能であるDeltaテーブル機能 IcebergCompatV2 が設定されます。このテーブル機能をサポートするクライアントのみが UniForm 対応テーブルに書き込むことができます。この機能を有効にしてDeltaテーブルに書き込むには、Databricks Runtime 14.3 LTS 以降を使用する必要があります。

UniForm をオフにするには、 delta.universalFormat.enabledFormats テーブルプロパティの設定を解除します。列マッピングを有効にした後でオフにしたり、Delta Lake リーダーおよびライタープロトコルバージョンへのアップグレードを元に戻すことはできません。

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

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

UniForm を使用するには、列マッピングを有効にする必要もあります。次の例のように、テーブルの作成中に UniForm を有効にすると、これは自動的に有効になります。

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

次の構文を使用して、既存のテーブルで UniForm を有効にできます。

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

注

この構文は、テーブル機能IcebergCompatV1を使用した UniForm のパブリックプレビューバージョンからアップグレードする場合にも機能します。

この構文は自動的に削除し、テーブルから削除します。既存のファイルは、Iceberg との互換性を保つために、必要に応じて書き換えられます。

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

注

Iceberg リーダークライアントとして BigQuery を使用する場合は、データレイアウトに関する BigQuery の要件に対応するために、Databricks で true spark.databricks.delta.write.dataFilesToSubdir を設定する必要があります。

制限事項を参照してください。

UniFormはいつアイスバーグメタデータを生成しますか?

Databricks は、 Delta トランザクションを完了したのと同じコンピュートを使用して、 Delta Lake 書き込みトランザクションが完了した後に、Iceberg メタデータ生成を非同期的にトリガーします。Iceberg メタデータの生成を手動でトリガーすることもできます。「 Iceberg メタデータ変換を手動でトリガーする」を参照してください。

Iceberg メタデータの生成に関連する書き込み待機時間を回避するために、コミットが頻繁に行われる Delta テーブルでは、複数の Delta コミットが 1 つの Iceberg コミットにバンドルされる場合があります。

Delta Lake では、常に 1 つの Iceberg メタデータ生成プロセスが進行中であることを保証します。 2 番目の並列 Iceberg メタデータ生成プロセスをトリガーするコミットは、Delta に正常にコミットされますが、非同期の Iceberg メタデータ生成はトリガーされません。これにより、頻繁にコミットする (コミット間の数秒から数分) ワークロードのメタデータ生成のカスケード待機時間が防止されます。

Delta および氷山の表のバージョンを参照してください。

氷山メタデータの生成ステータスを確認する

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

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

Databricks では、次のいずれかを実行して、これらのメタデータフィールドを確認できます。

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

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

SHOW TBLPROPERTIES <table-name>;

氷山メタデータ変換を手動でトリガーする

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

この操作は、通常の状態では必要ありませんが、次の場合に役立ちます。

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

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

MSCK REPAIR TABLE <table-name> SYNC METADATA

修復テーブルを参照してください。

メタデータ JSON パスを使用した読み取り

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

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

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

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

Databricks では、次のいずれかを実行して、このメタデータの場所を確認できます。

DESCRIBE EXTENDED table_nameによって返されたDelta Uniform Icebergセクションを確認しています。
カタログエクスプローラーを使用してテーブルのメタデータを確認します。
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 パスを手動で更新および更新する必要がある場合があります。古いバージョンを使用して Iceberg テーブルをクエリすると、Parquet データファイルが VACUUMを使用して Delta テーブルから削除されるため、エラーが発生することがあります。

Unity Catalog Iceberg カタログエンドポイントを使用して読み取る

一部の Iceberg クライアントは、Iceberg REST カタログに接続できます。 Unity Catalog は、エンドポイント /api/2.1/unity-catalog/icebergを使用して UniForm が有効になっている Delta テーブル用の Iceberg REST カタログ API の読み取り専用実装を提供します。この REST API の使用の詳細については、 Iceberg REST API の仕様を参照してください。

Iceberg カタログ API をサポートすることがわかっているクライアントには、Apache Spark、Flink、Trino などがあります。 UniForm を有効にした Delta テーブルを含む基盤となるクラウドオブジェクトストレージへのアクセスを設定する必要があります。構成の詳細については、Iceberg リーダークライアントのドキュメントを参照してください。

Databricks 個人用アクセストークンを生成して構成し、他のサービスが Unity Catalog に接続できるようにする必要があります。「 Databricks 自動化の認証 - 概要」を参照してください。

以下は、UniForm を Iceberg として読み取るように OSS Apache Spark を構成するための設定の例です。

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity"="org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token":"<your_personal_access_token>",
"spark.sql.catalog.unity.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

個人用アクセストークンを生成したワークスペースの完全な URL を <api-root>に置き換えます。

注

このメソッドを使用して Unity Catalog 内のテーブルをクエリする場合、オブジェクト識別子は次のパターンを使用します。

unity.<catalog-name>.<schema-name>.<table-name>

このパターンでは、 Unity Catalogと同じ 3 層の名前空間を使用しますが、プレフィックス unityが追加されます。

Delta および Iceberg テーブルのバージョン

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

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

制限

次の制限があります。

UniForm は、削除ベクトルが有効になっているテーブルでは機能しません。削除ベクトルとはを参照してください。
UniForm が有効になっているDeltaテーブルは、VOID タイプをサポートしません。
Iceberg クライアントは UniForm からのみ読み取ることができます。書き込みはサポートされていません。
Iceberg リーダークライアントには、UniForm に関係なく、個別の制限がある場合があります。選択したクライアントのドキュメントを参照してください。
Delta Sharingの受信者は、UniForm が有効な場合でも、テーブルをDeltaとしてのみ読み取ることができます。

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

UniForm で使用される一部の Delta Lake テーブル機能は、一部の Delta Sharing リーダークライアントではサポートされていません。 Delta Sharing使用してデータと AI アセットを安全に共有するを参照してください。

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

要件

ユニフォーム Delta を有効にする

UniFormはいつアイスバーグメタデータを生成しますか?

氷山メタデータの生成ステータス を確認する

氷山メタデータ変換 を手動でトリガーする

メタデータ JSON パス を使用した読み取り

Unity Catalog Iceberg カタログ エンドポイント を使用して読み取る