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 資格情報の販売」を参照してください。

クライアントで資格情報の自動販売がサポートされていない場合は、クライアントから 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 カタログ統合を構成します。

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 テーブルにアクセスする​

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

外部テーブル​

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

REST API の curl の例​

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

必要条件

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

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

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

外部テーブル

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

REST API の curl の例