Iceberg テーブルと Delta テーブルとの互換性を保つ Universal Format (UniForm)

[アーティクル]
03/21/2024

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

重要

従来の UniForm IcebergCompatV1 テーブルの機能のドキュメントについては、「レガシ UniForm IcebergCompatV1」をご覧ください。

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

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

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

Note

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

要件

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

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

Note

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

Delta UniForm の有効化

重要

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));

Note

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

この構文を使うと、テーブルの削除ベクトルが自動的に無効にされて消去されます。既存のファイルは、Iceberg と互換性を持つように必要に応じて書き換えられます。

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

Note

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

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

UniForm ではどのタイミングで Iceberg メタデータを生成しますか?

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

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

Delta Lake では、常に Iceberg メタデータの生成プロセスが 1 つだけ進行するようになっています。 2 つ目の並列した Iceberg メタデータの生成プロセスをトリガーするコミットは Delta に正常にコミットされますが、非同期的な Iceberg メタデータの生成はトリガーされません。これにより、頻繁にコミットされるワークロード (各コミット間の時間は数秒から数分) におけるメタデータ生成の多段的な待機時間を回避します。

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

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

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

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

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

DESCRIBE EXTENDED table_name によって返される Delta Uniform Iceberg セクションの確認。
カタログエクスプローラーでのテーブルメタデータの確認。
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 テーブルを登録するために、バージョン管理されたメタデータファイルへのパスを指定する必要があります。 UniForm で新しいバージョンの Delta テーブルを Iceberg に変換するたびに、新しいメタデータ JSON ファイルが作成されます。

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

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

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

Azure 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 パスの手動でのアップデートおよび更新が必要になる場合があります。 VACUUM によって Parquet データファイルが Delta テーブルから削除されるため、古いバージョンを使用して Iceberg テーブルに対してクエリを実行すると、エラーが発生する可能性があります。

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 リーダークライアントに関するドキュメントを参照してください。

他のサービスで Unity Catalog に接続できるように、Azure Databricks 個人用アクセストークンを生成して構成する必要があります。「Azure 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> に置き換えます。

Note

このメソッドを使用して 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 資産を安全に共有する」を参照してください。

Iceberg テーブルと Delta テーブルとの互換性を保つ Universal Format (UniForm)

要件

Delta UniForm の有効化

UniForm ではどのタイミングで Iceberg メタデータを生成しますか?

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

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

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

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

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

制限事項

その他のリソース

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