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 Catalog API を使用して、Delta テーブルがアクセスできるように設定する必要があります。Icebergクライアントを使用したDelta Lakeテーブルの読み取りを参照してください。

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

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

注記

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

注記

外部Icebergクライアントからアタッチされた行フィルターまたは列マスクを持つテーブルを読み取るには、必要なクライアントバージョンと構成について「クロスエンジン属性ベースのアクセス制御（ABAC）」を参照してください。

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

以下の例では、Iceberg REST Catalog API を介して Databricks のテーブルにアクセスするように Apache Spark を構成する方法を示します。Databricks では、OAuth および個人用アクセストークン (PAT) 認証をサポートしています。

複数のカタログ間でテーブルにアクセスするには、各カタログを個別に設定する必要があります。

注記

Iceberg Spark ランタイム JAR とクラウド固有のバンドル JAR を Spark パッケージに含める必要があります。ランタイム JAR のバージョンは、Spark および Scala のバージョンと一致する必要があります。たとえば、Spark 3.5 (Scala 2.12 を使用) の場合：

org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>

さらに、クラウド固有のバンドル:

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 統合に関するドキュメントを参照してください。これらの JAR は、Databricks クラスターから Iceberg テーブルにアクセスする際には不要です。

OAuth 認証

CLI
Python

Bash
pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.rest.auth.type=oauth2" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri=https://<workspace-url>/oidc/v1/token" \
  --conf "spark.sql.catalog.<spark-catalog-name>.credential=<oauth_client_id>:<oauth_client_secret>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.scope=all-apis"

Python
from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.rest.auth.type", "oauth2") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri", "https://<workspace-url>/oidc/v1/token") \
    .config("spark.sql.catalog.<spark-catalog-name>.credential", "<oauth_client_id>:<oauth_client_secret>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .config("spark.sql.catalog.<spark-catalog-name>.scope", "all-apis") \
    .getOrCreate()

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

<spark-catalog-name>: Spark セッションでカタログに割り当てる名前。
<uc-catalog-name>: テーブルを含む Unity Catalog のカタログの名前。
<oauth_client_id>: 認証プリンシパルの OAuth クライアント ID。
<oauth_client_secret>: 認証プリンシパルの OAuth クライアントシークレット。
<iceberg-version>：使用するIcebergバージョン（例：1.9.2）。
<workspace-url>: DatabricksワークスペースのURL 。例えば、 cust-success.cloud.databricks.com 。

PAT 認証

CLI
Python

Bash
pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.token=<token>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>"

Python
from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.token", "<token>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .getOrCreate()

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

<spark-catalog-name>: Spark セッションでカタログに割り当てる名前。
<uc-catalog-name>: テーブルを含む Unity Catalog のカタログの名前。
<token>：認証を行うプリンシパル用の個人用アクセストークン（PAT）。Databricksの個人アクセストークン (レガシー) を使用した認証」を参照してください。
<iceberg-version>：使用するIcebergバージョン（例：1.9.2）。
<workspace-url>: DatabricksワークスペースのURL 。例えば、 cust-success.cloud.databricks.com 。

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

制限事項

外部 Iceberg クライアントからマネージド Iceberg テーブルにアクセスする場合、次の制限が適用されます。

外部 Iceberg クライアントはビューにアクセスできません。
外部 Iceberg クライアントは、次のデータ型（UUID、Fixed(L)、TIME、および必須フィールドを持つネストされた STRUCT）を使用してマネージド Iceberg テーブルを作成できません。
外部のIcebergクライアントは、スナップショットの期限切れや孤立したファイルの削除などのテーブルメンテナンス操作を実行できません。

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

必要条件​

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

OAuth 認証​

PAT 認証​

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

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

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

外部テーブル​

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

REST API の curl の例​

制限事項​

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

必要条件

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

OAuth 認証

PAT 認証

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

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

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

外部テーブル

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

REST API の curl の例

制限事項