メインコンテンツまでスキップ

レガシーUniFormアイスバーグコンパットV1

important

このドキュメントは廃止されており、更新されない可能性があります。 このコンテンツに記載されている製品、サービス、またはテクノロジはサポートされなくなりました。 Deltaクライアントを使用したテーブルの読み取りIcebergを参照してください。

備考

プレビュー

この機能は、Databricks Runtime 13.2 以降で パブリック プレビュー 段階です。

Delta Universal Format (UniForm) を使用すると、Iceberg リーダー クライアントで Delta テーブルを読み取ることができます。

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

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

注記

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

必要条件​

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

Delta UniFormを有効にする​

important

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

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

次のテーブル プロパティは、Iceberg の UniForm サポートを有効にします。 iceberg のみが有効な値です。

'delta.universalFormat.enabledFormats' = 'iceberg'

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

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

CTAS ステートメントを使用して新しいテーブルを作成する場合は、次の例のように、カラムマッピングを手動で指定する必要があります。

SQL
CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

既存のテーブルを変更する場合は、次の例のように、これらのプロパティをすべて指定する必要があります。

SQL
ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

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

注記

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

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

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

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

Icebergメタデータの生成に関連する書き込みレイテンシーを回避するために、頻繁にコミットするDeltaテーブルでは、複数のDeltaコミットを 1 つのIcebergコミットにバンドルできます。

Delta Lake は、常に 1 つの Iceberg メタデータ生成プロセスのみが進行中であることを保証します。 2 番目の並列 Iceberg メタデータ生成プロセスをトリガーするコミットは、 Deltaに正常にコミットされますが、非同期の Iceberg メタデータ生成はトリガーされません。 これにより、コミットが頻繁に行われるワークロード (コミット間の数秒から数分) のメタデータ生成のレイテンシが連鎖的に発生するのを防ぐことができます。

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

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

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

メタデータフィールド

説明

converted_delta_version

Iceberg メタデータが正常に生成された Delta テーブルの最新バージョン。

converted_delta_timestamp

Iceberg メタデータが正常に生成された最新の Delta コミットのタイムスタンプ。

Databricks では、カタログ エクスプローラーを使用してこれらのメタデータ フィールドを確認できます。 これらのフィールドと値は、 REST API を使用してテーブルを取得するときにも返されます。

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

SQL
SHOW TBLPROPERTIES <table-name>;

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

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

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

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

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

SQL
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

このファイルのパスは、カタログエクスプローラを使用して検索できます。 UniForm が有効になっているテーブルの場合、Delta テーブルの詳細には 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"
    }
}
important

パスベースの Iceberg リーダー クライアントでは、現在のテーブル バージョンを読み取るために、メタデータの JSON パスを手動で更新および更新する必要がある場合があります。 Parquet データ ファイルが Delta テーブルから VACUUMで削除されるため、古いバージョンを使用して 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 リーダー クライアントのドキュメントを参照してください。

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

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

注記

この方法を使用して 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 テーブルでは、 LIST、 MAP、 VOID の各型はサポートされていません。
  • Iceberg クライアントは UniForm からのみ読み取ることができます。 書き込みはサポートされていません。
  • Iceberg リーダーのクライアントには、UniForm に関係なく、個別の制限がある場合があります。 選択したクライアントのドキュメントを参照してください。
  • Iceberg リーダー クライアント バージョン 1.2.0 以下は、Apache Spark によって書き込まれ INT96 タイムスタンプ タイプをサポートしていません。 この制限を回避するには、UniForm テーブルに書き込むノートブックで次のコードを使用します。 spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
  • Unity Catalog Iceberg エンドポイントのパブリック プレビュー バージョンは、大規模な本番運用ワークロード向けではありません。1 秒あたり 5 クエリのしきい値を超えると、レート制限が発生する可能性があります。

次の Delta Lake 機能は、UniForm が有効になっている場合に Delta クライアントで機能しますが、Iceberg ではサポートされていません。

  • データフィードを変更
  • Delta Sharing
に最終更新