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

備考

プレビュー

Unity Catalog Apache Iceberg REST Catalog 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カタログに登録された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の認証情報販売および外部システムを使用した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テーブルへの読み取りまたは書き込みアクセスを設定するには、以下の設定を完了する必要があります。

メタストアの 外部データアクセス を有効にします。「メタストアでの外部データアクセスの有効化」を参照してください。
統合を構成するプリンシパルに、テーブルを含むスキーマに対する 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": "<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>: ワークスペース 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カタログを介してテーブルにアクセスするための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>'
    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>: ワークスペース 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": "s3://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "s3.access-key-id": "<temporary-s3-access-key-id>",
    "s3.session-token":"<temporary-s3-session-token>",
    "s3.secret-access-key":"<temporary-secret-access-key>",
    "client.region":"<aws-bucket-region-for-metadata-location>"
  }
}

注記

expires-at-msフィールドは、認証情報の有効期限を示します。デフォルトの有効期限は1時間です。パフォーマンスを向上させるには、クライアントが認証情報の有効期限が切れるまでキャッシュし、新しい認証情報を要求するようにします。

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

必要条件​

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

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

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

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

外部テーブル​

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

REST API の curl の例​

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

必要条件

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

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

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

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

外部テーブル

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

REST API の curl の例