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

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

重要

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

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

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

注

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

UniForm はどのように機能しますか?

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

要件

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

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

注

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

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

UniForm Iceberg を有効にする

重要

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

UniForm をオフにするには、 delta.universalFormat.enabledFormats table プロパティの設定を解除します。 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バージョンを有効にしました。
Athena や Redshift など、Hive スタイルの Parquet ファイルをサポートしていない Iceberg エンジンから読み取る必要があります。

UniFormはいつ Iceberg メタデータを生成しますか?

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

注

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

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

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

Delta および Iceberg のテーブルのバージョンを参照してください。

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

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

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

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

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

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

最新バージョンの 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 REST カタログ API をサポートすることが知られているクライアントには、Apache Spark、Apache Flink、Trino、Snowflake などがあります。認証と承認の構成に加えて、UniForm が有効になっている Delta テーブルのファイルとメタデータを含むクラウドストレージの場所へのクライアントからのアクセスを構成する必要があります。設定の詳細については、Iceberg リーダークライアントのドキュメントを参照してください。

認証と承認

外部サービスから Unity エンドポイントを使用して Unity Catalog に登録されたデータにアクセスするには、次の 2 つの要件 api/2.1/unity-catalog/iceberg があります。

OAuthまたはDatabricks個人用アクセストークンを使用して認証します。「Databricks リソースへのアクセスを認証する」を参照してください。
メタストアの 外部データアクセス を有効にします。これにより、API が読み取っているスキーマに対する EXTERNAL USE SCHEMA 権限を持つユーザーへのアクセスが制限されます。「Unity Catalog のデータへの外部アクセスの制御」を参照してください。

Apache Spark の設定例

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

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing Uniform tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential": "<client-id>:<secret>",
"spark.sql.catalog.<spark-catalog-name>.scope": "all-apis,sql",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"

次の変数を代入します。

<uc-catalog-name>: Uniform テーブルを含む Unity Catalog のカタログの名前。
<workspace-url>: Databricks ワークスペースの URL。
<client-id>: サービスプリンシパルのクライアント ID。
<secret>: サービスプリンシパルのシークレット。

注

または、 PAT トークン(非推奨)を使用して、 "spark.sql.catalog.<spark-catalog-name>.token":"<token>"を使用してアクセスを設定することもできます。 PAT トークンを使用する場合は、 oauth-server-uri、 credential、および scope の設定を削除します。

これらの構成では、識別子 <catalog-name>.<schema-name>.<table-name>を使用して、Apache Spark で Uniform テーブルを Iceberg としてクエリできます。複数のカタログにまたがるテーブルにアクセスするには、各カタログを個別に設定する必要があります。

Spark 構成を使用して Unity Catalog のテーブルに対してクエリを実行する場合は、次の点に注意してください。

オブジェクト識別子は、パターン unity.<schema-name>.<table-name>を使用します。

このパターンでは、Unity Catalog で使用されているものと同じ 3 層の名前空間を使用しますが、カタログ名が unityに置き換えられています。
"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"必要があるのは、Iceberg 固有のストアドプロシージャを実行している場合のみです。
ストレージにクラウドプロバイダーを使用している場合は、クラウド固有の Iceberg バンドル jar を spark パッケージとして追加する必要があります。
- AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
- Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
- GCPの org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>
詳細については、 Spark の Iceberg AWS 統合のドキュメントを参照してください。

Snowflakeの構成例

以下は、SnowflakeがUnity Catalog Iceberg RESTと統合し、OAuthを使用してUniFormをIcebergとして読み取ることができるようにするための推奨構成設定の例です。

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg',
    WAREHOUSE = '<catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = '<workspace-url>/oidc/v1/token'
    OAUTH_CLIENT_ID = '<client-id>'
    OAUTH_CLIENT_SECRET = '<secret>'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;

次の変数を代入します。

<catalog-name>: UniForm テーブルを含む Unity Catalog のカタログの名前。
<workspace-url>: Databricks ワークスペースの URL。
<client-id>: サービスプリンシパルのクライアント ID。
<secret>: サービスプリンシパルのシークレット。

REST API の curl の例

また、この curl の例のような REST API 呼び出しを使用して、テーブルを読み込むこともできます。

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

その後、次のような応答を受け取る必要があります。

{
  "metadata-location": "gs://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "gcs.oauth2.token": "<temporary-oauth-token>",
    "gcs.oauth2.token-expires-at": "<epoch-ts-in-millis>"
  }
}

注

レスポンスの expires-at-ms フィールドは、認証情報の有効期限を示し、デフォルトの有効期限は 1 時間です。パフォーマンスを向上させるには、新しい資格情報を要求する前に、クライアントが有効期限まで資格情報をキャッシュするようにします。

制限

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

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

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