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

[アーティクル]
08/12/2024

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

重要

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

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

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

Note

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

UniForm のしくみ

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

要件

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

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

Note

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

削除ベクトルが有効になっている既存のテーブルで UniForm Iceberg を有効にする場合は、REORG を使用して削除ベクトルを無効化および消去します。 REORG を使用した有効化またはアップグレードについての記事をご覧ください。

UniForm Iceberg を有効にする

重要

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

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

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

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

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

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

テーブル作成時に有効にする

UniForm Iceberg を使用するには、列マッピングを有効にする必要があります。次の例のように、テーブル作成時に UniForm Iceberg を有効にした場合、これは自動的に有効化されます。

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

既存のテーブルを変更して有効にする

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

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

`REORG` を使用して有効化またはアップグレードする

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

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

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

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

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

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

Note

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

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

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

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

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

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

一般に、Delta テーブルのバージョンが、コミットタイムスタンプまたはバージョン ID のいずれかで、Iceberg バージョンと一致することはありません。 Delta テーブルのどのバージョンが Iceberg テーブルのどのバージョンに対応するかを確認する場合は、対応するテーブルのプロパティを使用できます。「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 ツールと API の認証を参照してください。

以下は、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 が追加されています。

制限事項

すべての UniForm テーブルには、次の制限があります。

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

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

次の方法で共有

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

UniForm のしくみ

要件

UniForm Iceberg を有効にする

テーブル作成時に有効にする

既存のテーブルを変更して有効にする

`REORG` を使用して有効化またはアップグレードする

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

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

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

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

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

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

制限事項

フィードバック

その他のリソース

次の方法で共有

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

UniForm のしくみ

要件

UniForm Iceberg を有効にする

テーブル作成時に有効にする

既存のテーブルを変更して有効にする

REORG を使用して有効化またはアップグレードする

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

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

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

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

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

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

制限事項

フィードバック

その他のリソース

`REORG` を使用して有効化またはアップグレードする

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