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

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

備考

プレビュー

Unity CatalogApacheIcebergRESTカタログAPI は、Databricks Runtime16.4LTS 以降で パブリック プレビュー 段階です。

Unity Catalog には、一般公開されている Iceberg REST Catalog API の読み取り専用実装があります。このエンドポイントは、Iceberg 読み取りが有効になっている Delta テーブルを読み取る場合に推奨されます。詳細については 、「クライアントからの Databricksテーブルの読み取り (レガシ)」 を参照してください。Iceberg

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

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

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

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

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

注記

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 テーブルの読み取りまたは書き込みへのアクセスを構成するには、次の構成手順を完了する必要があります。

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

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

"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>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/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_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 セッションでカタログに割り当てる名前。
  • <workspace-url>: Databricks ワークスペースの URL。
  • <oauth_client_id>: 認証プリンシパルの OAuth クライアント ID。
  • <oauth_client_secret>: 認証プリンシパルの OAuth クライアントシークレット。

これらの構成では、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 テーブルを読み取る​

次に、 で カタログに接続して テーブルを読み取るための推奨される構成設定の例を示します。SnowflakeDatabricksIcebergRESTUnity Catalog

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>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  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>: Databricks ワークスペースの URL。
  • <token>: 統合を構成するプリンシパルの PAT トークン。

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

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

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

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

  • <workspace-url>: Databricks ワークスペースの URL。
  • <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 時間です。 パフォーマンスを向上させるには、新しい資格情報を要求する前に、クライアントが有効期限まで資格情報をキャッシュするようにします。

に最終更新
Was this article helpful?