Apache Iceberg クライアントから Databricks テーブルにアクセスする

備考

プレビュー

Unity Catalog Apache Iceberg RESTカタログAPI 、 Databricks Runtime 16.4 LTS以降でパブリックプレビュー段階にあります。このエンドポイントは、Iceberg クライアントからのテーブルの読み取りと書き込みに推奨されます。

Unity Catalog には、読み取り専用の Iceberg REST Catalog API エンドポイントもあります。これはレガシーエンドポイントです。「Apache Iceberg クライアント (レガシ) から Databricks テーブルを読み取る」を参照してください。

Apache Iceberg REST カタログを使用すると、Apache Spark、Apache Flink、Trino などのサポートされているクライアントが、Databricks 上の Unity Catalog に登録された Iceberg テーブルとの間で読み取りおよび書き込みを行うことができます。

サポートされている統合の完全な一覧については、「 Unity Catalog の統合」を参照してください。

Unity Catalog Iceberg カタログエンドポイントを使用する

Unity Catalog は、Iceberg REST カタログ API 仕様の実装を提供します。

エンドポイント /api/2.1/unity-catalog/iceberg-restを使用してアクセスを設定します。この REST API の使用の詳細については、 Iceberg REST API の仕様を参照してください。

重要

Iceberg REST カタログエンドポイントに使用されるワークスペース URL には、ワークスペース ID を含める必要があります。ワークスペース ID がないと、API リクエストは予期される応答ではなく、ログインページへの303リダイレクトを返す可能性があります。

ワークスペースの URL とワークスペース ID を確認するには、「ワークスペースのインスタンス名、URL、および ID」を参照してください。

注記

Databricks は、一部の Iceberg リーダークライアント向けに資格情報の自動販売を導入しました。 Databricks では、サポートされているシステムのクラウドストレージの場所へのアクセスを制御するために、資格情報の自動販売を使用することをお勧めします。「外部システムアクセスのための Unity Catalog 資格情報の販売」を参照してください。

クライアントで資格情報の自動販売がサポートされていない場合は、クライアントから Delta または Iceberg テーブルのファイルとメタデータを含むストレージの場所へのアクセスを構成する必要があります。設定の詳細については、Iceberg クライアントのドキュメントを参照してください。

必要条件

Databricks は、Unity Catalog の一部としてテーブルへの Iceberg REST カタログアクセスをサポートしています。これらのエンドポイントを使用するには、ワークスペースで Unity Catalog を有効にする必要があります。次のテーブルタイプには、Iceberg REST カタログからアクセスできます。

トピック	読み取り	書き込み
マネージド Iceberg	Yes	Yes
海外 Iceberg	Yes	No
マネージド Delta ( Iceberg 読み取りが有効)	Yes	No
外部 Delta ( Iceberg 読み取りが有効)	Yes	No

外部 Iceberg テーブルは、Iceberg REST Catalog API を介して読み取るときに自動的に更新されません。更新するには、 REFRESH FOREIGN TABLE を実行して最新のスナップショットを読み取る必要があります。Foreign Iceberg テーブルでの資格情報の自動販売はサポートされていません。

注記

Delta テーブルは、Iceberg REST Catalog API を介してアクセスできるように構成する必要があります。Deltaクライアントを使用したテーブルの読み取りIcebergを参照してください。

Iceberg REST カタログを使用して Iceberg クライアントから Databricks テーブルの読み取りまたは書き込みへのアクセスを構成するには、次の構成手順を完了する必要があります。

メタストアの 外部データアクセス を有効にします。「メタストアでの外部データアクセスの有効化」を参照してください。
統合を構成するプリンシパルに、テーブルを含むスキーマに対する EXTERNAL USE SCHEMA 権限を付与します。「プリンシパルに Unity Catalog 特権を付与する」を参照してください。
Databricks個人アクセストークンまたはOAuthを使用して認証します。「Databricks リソースへのアクセスを承認する」を参照してください。

注記

Iceberg 仕様では、単一のテーブルスナップショット内で重複するデータファイルが許可されません。この発生を防ぐために、Unity Catalog は、これが検出されると、外部エンジンが重複したデータファイルをテーブルにコミットするのをブロックします。

Apache Spark での Iceberg テーブルの使用

次に、OAuth 認証を使用して Iceberg REST Catalog API 経由で Databricks テーブルにアクセスするように Apache Spark を構成する方法の例を示します。

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

# Configuration for accessing 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>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

次の変数を置き換えます。

<uc-catalog-name>: テーブルを含む Unity Catalog のカタログの名前。
<spark-catalog-name>: Spark セッションでカタログに割り当てる名前。
<oauth_client_id>: 認証プリンシパルの OAuth クライアント ID。
<oauth_client_secret>: 認証プリンシパルの OAuth クライアントシークレット。
<workspace-url>: ワークスペース ID を含む Databricksワークスペース URL 。たとえば、 cust-success.cloud.databricks.com/?o=6280049833385130 。

これらの構成では、Apache Spark を使用して Unity Catalog のテーブルに対してクエリを実行できます。複数のカタログにまたがるテーブルにアクセスするには、各カタログを個別に設定する必要があります。

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

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"必要があるのは、Iceberg 固有のストアドプロシージャを実行している場合のみです。
Databricks はすべてのテーブルにクラウドオブジェクトストレージを使用します。iceberg-spark-runtime 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 統合のドキュメントを参照してください。

注記

これらの構成は、Databricks から Iceberg テーブルにアクセスする場合は必要ありません。外部 Iceberg JAR の Databricks クラスタリングへのロードはサポートされていません。

Snowflake を使用して Databricks テーブルにアクセスする

Snowflake では、Iceberg REST カタログを通じてテーブルにアクセスするためのオプションとして、Snowflake のカタログにリンクされたデータベース経由と外部テーブル経由の 2 つが提供されています。

どちらのオプションでも、最初に Snowflake カタログ統合を構成します。

SQL
CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

次の変数を置き換えます。

<catalog-integration-name>: Snowflakeに登録されたカタログに割り当てる名前。
<uc-schema-name>: アクセスする必要があるスキーマの名前 Unity Catalog 。
<uc-catalog-name>: アクセスする必要がある Unity Catalog のカタログの名前。
<workspace-url>: ワークスペース ID を含む Databricksワークスペース URL 。たとえば、 https://cust-success.cloud.databricks.com/?o=6280049833385130またはhttps://adb-1234567890123456.12.azuredatabricks.net 。
<token>: 統合を構成するプリンシパルの PAT トークン。

カタログリンクデータベース

Snowflake のカタログにリンクされたデータベースは、 Unity Catalog と自動的に同期して、スキーマと Iceberg テーブルを検出します。これにより、手動でメタデータを更新する必要がなくなります。

Snowflake カタログ統合を構成した後、 Snowflake のドキュメントを参照して、テーブルにアクセスするためのカタログリンクデータベースを作成します。

重要

Snowflake から読み取り専用の Databricks テーブルに書き込もうとすると、エラーが発生する可能性があります。サポートされている操作については、 Snowflake のドキュメントを参照してください。

外部テーブル

あるいは、Snowflake カタログ統合を作成した後で外部テーブルを作成することもできます。この方法では、更新を確認するためにメタデータを手動で更新する必要があります。

SQL
CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Databricks テーブルを PyIceberg と共に使用する

PyIceberg を使用して Databricks テーブルにアクセスするには、必要な依存関係とともに PyIceberg をインストールする必要があります。PyIceberg では、データの読み取りやテーブルメタデータの検査などのテーブル操作にpyarrowが必要です。pyarrow追加機能を使用して PyIceberg をインストールします:

Bash
pip install "pyiceberg[pyarrow]"

注記

pyarrowをインストールしないと、テーブルの記述や読み取りなどの操作は失敗します。オプションの依存関係の完全なリストについては、 PyIceberg のドキュメントを参照してください。

以下は、PyIceberg が Unity Catalog の Iceberg REST Catalog に接続して Databricks テーブルにアクセスできるようにするための構成設定の例です。

YAML
catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

次の変数を置き換えます。

<workspace-url>: ワークスペース ID を含む Databricksワークスペース URL 。たとえば、 cust-success.cloud.databricks.com/?o=6280049833385130 。
<uc-catalog-name>: アクセスする必要がある Unity Catalog のカタログの名前。
<token>: 統合を構成するプリンシパルの PAT トークン。

PyIceberg REST カタログ設定のドキュメンテーションを参照してください。

REST API の curl の例

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

Bash
curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/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 時間です。パフォーマンスを向上させるには、新しい資格情報を要求する前に、クライアントが有効期限まで資格情報をキャッシュするようにします。

Unity Catalog Iceberg カタログ エンドポイントを使用する​

必要条件​

Apache Spark での Iceberg テーブルの使用​

Snowflake を使用して Databricks テーブルにアクセスする​

カタログリンクデータベース​

外部テーブル​

Databricks テーブルを PyIceberg と共に使用する​

REST API の curl の例​

Unity Catalog Iceberg カタログエンドポイントを使用する

必要条件

Apache Spark での Iceberg テーブルの使用

Snowflake を使用して Databricks テーブルにアクセスする

カタログリンクデータベース

外部テーブル

Databricks テーブルを PyIceberg と共に使用する

REST API の curl の例