レガシ UniForm IcebergCompatV1

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

重要

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

重要

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

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

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

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

Note

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

要件

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

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

Delta UniForm の有効化

重要

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

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

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

'delta.universalFormat.enabledFormats' = 'iceberg'

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

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

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

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

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

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = '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 では、Catalog Explorer を使用してこれらのメタデータフィールドを確認できます。これらのフィールドと値は、テーブルを取得するために 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

Catalog Explorer を使用して、このファイルのパスを確認できます。 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"
    }
}

重要

パスベースの 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 テーブルは、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

次の方法で共有

レガシ UniForm IcebergCompatV1

要件

Delta UniForm の有効化

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

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

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

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

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

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

制限事項

フィードバック

その他のリソース

次の方法で共有

レガシ UniForm IcebergCompatV1

要件

Delta UniForm の有効化

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

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

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

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

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

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

制限事項

フィードバック

その他のリソース

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