メインコンテンツまでスキップ
に最終更新

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

Apache Iceberg RESTカタログを使用すると、Apache Spark、Apache Flink、Trinoなどの対応クライアントが、Databricks上のUnityカタログに登録されたIcebergテーブルからデータの読み書きを行うことができます。

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

注記

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

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の認証情報販売および外部システムを使用したIcebergテーブルへのアクセスを参照してください。

クライアントで資格情報の自動販売がサポートされていない場合は、クライアントから 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 RESTカタログAPIを使用してテーブルを読み取る場合、外部のIcebergテーブルは自動的に更新されません。更新するには、 REFRESH FOREIGN TABLEを実行して最新のスナップショットを読み取る必要があります。海外のIcebergテーブルでの認証情報販売はサポートされていません。

注記

Iceberg RESTカタログAPIを使用してアクセスできるようにするには、Deltaテーブルを設定する必要があります。IcebergクライアントでDeltaテーブルを読み込む方法については、こちらをご覧ください。

Iceberg RESTカタログを使用してIcebergクライアントから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": "<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_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>: DatabricksワークスペースのURL 。例えば、 cust-success.cloud.databricks.com 。

これらの構成では、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カタログを介してテーブルにアクセスするための2つのオプションを提供しています。Snowflakeのカタログリンクされたデータベースを使用する方法と、外部テーブルを使用する方法です。

どちらのオプションを選択する場合でも、まずSnowflakeカタログとの連携を設定してください。Databricksは、Snowflakeカタログ統合において、以下の認証方法をサポートしています。

  • Bearer トークン : Databricksの個人アクセス権 (PAT) またはOAuthトークンを使用します。 すべてのクラウド環境でサポートされています。
  • Entra サービスプリンシパルOAuth ( Azureのみ) : Microsoft Entra ID サービスプリンシパルを使用して、Entra VPN エンドポイントに対して直接認証します。

RESTカタログ統合におけるSnowflake認証オプションの詳細については、 Snowflakeのドキュメントを参照してください。

Snowflakeのベアラートークン認証​

以下の例では、ベアラートークンを使用してSnowflakeカタログの統合を設定します。Databricksパーソナル アクセストークン(PAT) またはDatabricksプリンシパルから生成されたOAuthトークンを使用できます。 OAuth生成の詳細については、 「 OAuthを使用したDatabricksへのサービス プリンシパル アクセスの許可」を参照してください。

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>: DatabricksワークスペースのURL 。例えば、 https://cust-success.cloud.databricks.comまたは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>: DatabricksワークスペースのURL 。例えば、 cust-success.cloud.databricks.com 。

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

このページの見出し