BigLake metastore Iceberg REST カタログを使用する

BigLake metastore の Apache Iceberg REST カタログは、新しいワークフローで BigLake metastore を使用する推奨の方法です。すべての Iceberg データに関して単一の信頼できる情報源を提供することで、クエリエンジン間の相互運用性を実現します。これにより、Apache Spark などのクエリエンジンは、Iceberg テーブルを検出してメタデータを読み取り、一貫した方法で管理できます。

このアプローチは、オープンソース エンジンを使用して Cloud Storage のデータにアクセスし、BigQuery などの他のエンジンとの相互運用性が必要な場合に適しています。きめ細かいアクセス制御のための認証情報の提供や、クロスリージョン レプリケーションと障害復旧などの機能をサポートしています。

一方、BigQuery 用のカスタム Iceberg カタログは、以前のインテグレーションです。既存のワークフローでは引き続き使用できますが、REST カタログではより標準化された機能豊富なエクスペリエンスが提供されます。

始める前に

続行する前に、BigLake metastore について理解しておいてください。

1. Verify that billing is enabled for your Google Cloud project.

2. Enable the BigLake API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

必要なロール

BigLake metastore で Iceberg REST カタログを使用するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• カタログ ユーザー アクセス、ストレージ アクセス、カタログの認証情報ベンダー モードの管理などの管理タスクを行います。
  • プロジェクトに対する BigLake 管理者 （roles/biglake.admin）
  • Cloud Storage バケットに対するストレージ管理者 （roles/storage.admin）
• 認証情報ベンディング モードでテーブルデータを読み取る: プロジェクトに対する BigLake 閲覧者 （roles/biglake.viewer）
• 認証情報ベンディング モードでテーブルデータを書き込む: プロジェクトに対する BigLake 編集者 （roles/biglake.editor）
• 非認証情報ベンディング モードでカタログ リソースとテーブルデータを読み取る:
  • プロジェクトに対する BigLake 閲覧者 （roles/biglake.viewer）
  • Cloud Storage バケットに対する Storage オブジェクト閲覧者 （roles/storage.objectViewer）
• カタログ リソースを管理し、認証情報ベンディング モード以外でテーブルデータを書き込む:
  • プロジェクトに対する BigLake 編集者 （roles/biglake.editor）
  • Cloud Storage バケットに対する Storage オブジェクト ユーザー （roles/storage.objectUser）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

制限事項

Iceberg REST カタログには次の制限があります。

• 認証情報ベンディング モードを使用する場合は、io-impl プロパティを org.apache.iceberg.gcp.gcs.GCSFileIO に設定する必要があります。デフォルトの org.apache.iceberg.hadoop.HadoopFileIO はサポートされていません。
• Trino は、Compute Engine 2.3 イメージ バージョン 2.3.16 以降を使用する場合にのみ、BigQuery カタログ フェデレーションでサポートされます。

カタログ リソース

BigLake Metastore の Apache Iceberg REST カタログは、リソースの階層を使用してデータを整理します。

Apache Iceberg REST カタログ リソース

次の表は、BigLake metastore の Apache Iceberg REST カタログで使用されるリソースの概要を示しています。

リソース	説明
カタログ	最上位のコンテナであるカタログを使用すると、Namespace とテーブルを異なるカタログに分割して、論理グループに整理できます。
名前空間	カタログ内のテーブルを整理するために使用される論理グループ。データベース、スキーマ、ディレクトリのように機能します。
テーブル	テーブルには、クエリ可能な行と列の定義が含まれています。

サポートされているカタログ

クライアントを構成するときに、ウェアハウスのロケーションを指定します。この選択により、カタログの動作と他の Google Cloudサービスとの統合方法が決まります。

カタログ タイプ	説明
Cloud Storage バケット	カタログ内のすべてのデータは単一の Cloud Storage バケットに保存されます。複数のバケット間で共有されるデータには、複数のカタログが必要です。
BigQuery フェデレーション	Iceberg REST カタログを使用して、BigQuery に表示されるテーブルの管理とクエリを実行できます。詳細については、BigQuery でカタログ フェデレーションを使用するをご覧ください。

カタログ ウェアハウスの詳細

推奨

• Cloud Storage バケット ウェアハウス（gs://）: これは、カタログが指定した Cloud Storage バケット内の Iceberg メタデータとデータファイルを直接管理する標準的なアプローチです。このオプションを使用すると、データ レイアウトを直接制御でき、きめ細かいアクセス制御のための認証情報のベンディングがサポートされます。これにより、Apache Iceberg 用の BigLake テーブルを作成して管理できます。

  重要: Cloud Storage バケットをウェアハウスとして使用するカタログの場合、カタログ名はカタログ リソースの ID でもあります。

  たとえば、カタログを保存するためにバケットを作成し、そのバケットに iceberg-bucket という名前を付けた場合、カタログ名とバケット名の両方が iceberg-bucket になります。これは、後で BigQuery でカタログをクエリするときに P.C.N.T 構文を使用して使用されます。たとえば、my-project.biglake-catalog-id.quickstart_namespace.quickstart_table のようにします。

旧 SKU

• BigQuery 連携（bq://）: この方法では、Iceberg REST カタログを使用して、BigQuery に表示されるテーブルを管理およびクエリできます。カタログ リソースを作成する必要はありません。詳細については、BigQuery でカタログ連携を使用するをご覧ください。

P.C.N.T の命名規則

BigQuery から BigLake Metastore テーブルをクエリする場合は、4 部構成の命名構造を使用します。これは P.C.N.T と呼ばれることがよくあります。

• Project: カタログを所有する Google Cloud プロジェクト ID。
• Catalog: BigLake metastore カタログの名前。
• Namespace: Iceberg 名前空間（BigQuery データセットに相当）。
• Table: テーブルの名前。

例: my-project.biglake-catalog-id.my-namespace.my-table

Iceberg REST カタログを設定する

BigLake metastore で Apache Iceberg REST カタログを使用する一般的な手順は次のとおりです。

1. カタログ ウェアハウスのロケーション（Cloud Storage または BigQuery）を理解して選択します。
2. Cloud Storage gs:// ウェアハウスを使用している場合は、ウェアハウスの場所を指すカタログを作成します。
3. Iceberg REST カタログを使用するようにクライアント アプリケーションを構成します。
4. テーブルを整理するための Namespace またはスキーマを作成します。
5. 構成したクライアントを使用してテーブルを作成し、クエリを実行します。

カタログの作成

エンドユーザー認証情報または認証情報ベンディング モードを使用するカタログを作成できます。

• エンドユーザー認証情報を使用すると、カタログはアクセスしているエンドユーザーの ID を Cloud Storage に渡して、認可チェックを行います。

• 認証情報のベンディングは、BigLake Metastore 管理者が BigLake Metastore リソースに対する権限を直接制御できるようにするストレージ アクセス委任メカニズムです。これにより、カタログ ユーザーが Cloud Storage バケットに直接アクセスする必要がなくなります。これにより、BigLake 管理者は特定のデータファイルに対する権限をユーザーに付与できます。

エンドユーザー認証情報

コンソール

1. Google Cloud コンソールで [BigLake] ページを開きます。

   BigLake に移動

2. [カタログを作成] をクリックします。

3. [Cloud Storage バケットを選択] フィールドに、カタログで使用する Cloud Storage バケットの名前を入力します。または、[参照] をクリックして、既存のバケットを選択するか、新しいバケットを作成します。Cloud Storage バケットごとに 1 つのカタログのみを使用できます。

4. [Authentication method] で [End-user credentials] を選択します。

5. [作成] をクリックします。

gcloud

gcloud beta biglake iceberg catalogs create コマンドを使用します。

gcloud beta biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

次のように置き換えます。

• CATALOG_NAME: カタログの名前。Apache Iceberg 用のマネージド BigLake テーブルの場合、この名前は REST カタログで使用される Cloud Storage バケット ID と一致することがよくあります。たとえば、バケットが gs://bucket-id の場合、カタログ名は bucket-id になることがあります。この名前は、BigQuery からこれらのテーブルをクエリするときにカタログ識別子としても使用されます。
• PROJECT_ID: 実際の Google Cloud プロジェクト ID。

認証情報ベンディング モード

カタログ管理者は、カタログの作成時または更新時に認証情報ベンダーを有効にします。カタログ ユーザーは、Iceberg REST カタログを構成するときにアクセス委任を指定することで、Iceberg REST カタログにダウン スコープされたストレージ認証情報を返すように指示できます。

コンソール

1. Google Cloud コンソールで、[BigLake] ページを開きます。

   BigLake に移動

2. [ カタログを作成] をクリックします。[カタログの作成] ページが開きます。

3. [Cloud Storage バケットを選択] に、カタログで使用する Cloud Storage バケットの名前を入力します。または、[参照] をクリックして、既存のバケットのリストから選択するか、新しいバケットを作成します。Cloud Storage バケットごとに 1 つのカタログのみを使用できます。

4. [認証方法] で、[認証情報ベンダーモード] を選択します。

5. [作成] をクリックします。

   カタログが作成され、[カタログの詳細] ページが開きます。

6. [認証方法] で、[バケットの権限を設定] をクリックします。

7. ダイアログで [確認] をクリックします。

   これにより、カタログのサービス アカウントにストレージ バケットに対するストレージ オブジェクト ユーザー ロールがあることが確認されます。

クライアント アプリケーションを構成する

カタログを作成したら、それを使用するようにクライアント アプリケーションを構成します。これらの例は、認証情報ベンダーを使用する場合と使用しない場合の設定方法を示しています。

クラスタ

Dataproc で Iceberg REST カタログを使用して Spark を使用するには、まず Iceberg コンポーネントを含むクラスタを作成します。

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

次のように置き換えます。

• CLUSTER_NAME: クラスタの名前。
• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• REGION: Dataproc クラスタのリージョン。
• DATAPROC_VERSION: Dataproc イメージ バージョン（例: 2.2）。

クラスタを作成したら、Iceberg REST カタログを使用するように Spark セッションを構成します。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

次のように置き換えます。

• CATALOG_NAME: Iceberg REST カタログの名前。
• APP_NAME: Spark セッションの名前。
• WAREHOUSE_PATH: ウェアハウスのパス。gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログ フェデレーションを使用するには、BigQuery でカタログ フェデレーションを使用するをご覧ください。
• PROJECT_ID: Iceberg REST カタログの使用に対して課金されるプロジェクト。Cloud Storage バケットを所有するプロジェクトとは異なる場合があります。REST API を使用する場合のプロジェクト構成の詳細については、システム パラメータをご覧ください。

認証情報ベンディングで構成する

認証情報ベンディングを使用するには、認証情報ベンディング モードのカタログを使用し、次の行を SparkSession ビルダーに追加して、Iceberg REST カタログ リクエストに X-Iceberg-Access-Delegation ヘッダーを追加し、値を vended-credentials に設定する必要があります。

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

認証情報ベンディングの例

次の例では、認証情報のベンディングを使用してクエリエンジンを構成します。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳細については、Iceberg ドキュメントの RESTCatalog のヘッダーをご覧ください。

Dataproc クラスタは、次のリリースで Iceberg の Google 認証フローをサポートしています。

• Dataproc on Compute Engine 2.2 イメージ バージョン 2.2.65 以降。
• Dataproc on Compute Engine 2.3 イメージ バージョン 2.3.11 以降。

サーバーレス

次の構成で PySpark バッチ ワークロードを Google Cloud Apache Spark 向け Serverless に送信します。

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

次のように置き換えます。

• PYSPARK_FILE: PySpark アプリケーション ファイルへの gs:// Cloud Storage パス。
• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• REGION: Dataproc バッチ ワークロードのリージョン。
• RUNTIME_VERSION: Apache Spark 用サーバーレスのランタイム バージョン（例: 2.2）。
• CATALOG_NAME: Iceberg REST カタログの名前。
• WAREHOUSE_PATH: ウェアハウスのパス。gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログ フェデレーションを使用するには、BigQuery でカタログ フェデレーションを使用するをご覧ください。

認証情報ベンディングで構成する

認証情報ベンディングを使用するには、認証情報ベンディング モードのカタログを使用し、次の行を Serverless for Apache Spark 構成に追加して、Iceberg REST カタログ リクエストに vended-credentials の値を持つ X-Iceberg-Access-Delegation ヘッダーを追加する必要があります。

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

認証情報ベンディングの例

次の例では、認証情報のベンディングを使用してクエリエンジンを構成します。

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

詳細については、Iceberg ドキュメントの RESTCatalog のヘッダーをご覧ください。

Apache Spark 用 Serverless は、次のランタイム バージョンで Iceberg の Google 認証フローをサポートしています。

• Serverless for Apache Spark 2.2 ランタイム 2.2.60 以降
• Serverless for Apache Spark 2.3 ランタイム 2.3.10 以降

Trino

Iceberg REST カタログで Trino を使用するには、Trino コンポーネントを含む Dataproc クラスタを作成し、gcloud dataproc clusters create --properties フラグを使用してカタログ プロパティを構成します。次の例では、CATALOG_NAME という名前の Trino カタログを作成します。

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

次のように置き換えます。

• CLUSTER_NAME: クラスタの名前。
• REGION: Dataproc クラスタのリージョン。
• DATAPROC_VERSION: Dataproc イメージ バージョン（例: 2.2）。
• NETWORK_ID: クラスタ ネットワーク ID。詳細については、Dataproc クラスタのネットワーク構成をご覧ください。
• CATALOG_NAME: Iceberg REST カタログを使用する Trino カタログの名前。
• WAREHOUSE_PATH: ウェアハウスのパス。gs://CLOUD_STORAGE_BUCKET_NAME を使用します。
• PROJECT_ID: BigLake metastore に使用する Google Cloud プロジェクト ID。

クラスタの作成後、メイン VM インスタンスに接続し、Trino CLI を使用します。

trino --catalog=CATALOG_NAME

Dataproc Trino は、次のリリースで Iceberg の Google 認証フローをサポートしています。

• Dataproc on Compute Engine 2.2 ランタイム バージョン 2.2.65 以降
• Dataproc on Compute Engine 2.3 ランタイム バージョン 2.3.11 以降
• Dataproc on Compute Engine 3.0 はサポートされていません。

認証情報ベンディングで構成する

Dataproc Trino では認証情報のベンダーはサポートされていません。

Iceberg 1.10 以降

オープンソースの Iceberg 1.10 以降のリリースでは、GoogleAuthManager での Google 認証フローのサポートが組み込まれています。次に、BigLake metastore Iceberg REST カタログを使用するように Apache Spark を構成する例を示します。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

次のように置き換えます。

• CATALOG_NAME: Iceberg REST カタログの名前。
• APP_NAME: Spark セッションの名前。
• WAREHOUSE_PATH: ウェアハウスのパス。gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログ フェデレーションを使用するには、BigQuery でカタログ フェデレーションを使用するをご覧ください。
• PROJECT_ID: Iceberg REST カタログの使用に対して課金されるプロジェクト。Cloud Storage バケットを所有するプロジェクトとは異なる場合があります。REST API を使用する場合のプロジェクト構成の詳細については、システム パラメータをご覧ください。

認証情報ベンディングで構成する

上記の例では、認証情報のベンディングは使用されていません。認証情報ベンディングを使用するには、認証情報ベンディング モードのカタログを使用し、SparkSession ビルダーに次の行を追加して、Iceberg REST カタログ リクエストに値 vended-credentials の X-Iceberg-Access-Delegation ヘッダーを追加する必要があります。

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

認証情報ベンディングの例

次の例では、認証情報のベンディングを使用してクエリエンジンを構成します。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳細については、Iceberg ドキュメントの RESTCatalog のヘッダーをご覧ください。

以前の Iceberg リリース

1.10 より前のオープンソース Iceberg リリースでは、次の内容でセッションを構成することで、標準の OAuth 認証を構成できます。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

次のように置き換えます。

• CATALOG_NAME: Iceberg REST カタログの名前。
• APP_NAME: Spark セッションの名前。
• WAREHOUSE_PATH: ウェアハウスのパス。gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログ フェデレーションを使用するには、BigQuery でカタログ フェデレーションを使用するをご覧ください。
• PROJECT_ID: Iceberg REST カタログの使用に対して課金されるプロジェクト。Cloud Storage バケットを所有するプロジェクトとは異なる場合があります。REST API を使用する場合のプロジェクト構成の詳細については、システム パラメータをご覧ください。
• TOKEN: 1 時間有効な認証トークン。たとえば、gcloud auth application-default print-access-token を使用して生成されたトークン。

認証情報ベンディングで構成する

上記の例では、認証情報のベンディングは使用されていません。認証情報ベンディングを使用するには、認証情報ベンディング モードのカタログを使用し、SparkSession ビルダーに次の行を追加して、Iceberg REST カタログ リクエストに値 vended-credentials の X-Iceberg-Access-Delegation ヘッダーを追加する必要があります。

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

認証情報ベンディングの例

次の例では、認証情報のベンディングを使用してクエリエンジンを構成します。

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

詳細については、Iceberg ドキュメントの RESTCatalog のヘッダーをご覧ください。

Namespace またはスキーマを作成する

クライアントを構成したら、テーブルを整理するための Namespace またはスキーマを作成します。Namespace またはスキーマを作成する構文は、クエリエンジンによって異なります。次の例は、Spark と Trino を使用して作成する方法を示しています。

注意: 認証情報ベンディングを使用している場合は、他の Namespace またはスキーマ内に Namespace またはスキーマを作成しないでください。作成すると、ユーザーが意図しないリソースにアクセスできるようになる可能性があります。

Spark

Cloud Storage ウェアハウス

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

NAMESPACE_NAME は、Namespace の名前に置き換えます。

Trino

Cloud Storage ウェアハウス

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

次のように置き換えます。

• CATALOG_NAME: Iceberg REST カタログを使用する Trino カタログの名前。
• SCHEMA_NAME: スキーマの名前。

BigQuery でテーブルをクエリする

BigQuery の Iceberg REST カタログを使用して作成したテーブルに対してクエリを実行する方法は、Cloud Storage バケット ウェアハウスまたは BigQuery フェデレーションを使用しているかどうかによって異なります。

• Cloud Storage バケット ウェアハウス: クライアントを gs:// ウェアハウス パスで構成した場合は、4 部構成の名前（P.C.N.T）project.catalog.namespace.table を使用して BigQuery からテーブルをクエリします。catalog コンポーネントは、BigLake metastore カタログ リソースの名前です。詳細については、テーブルにクエリを実行するをご覧ください。

• BigQuery 連携: bq:// ウェアハウス パスを使用してクライアントを構成した場合、作成したテーブルは BigQuery に表示され、標準の BigQuery SQL を使用して直接クエリできます。

  SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

  次のように置き換えます。

  • NAMESPACE_NAME: 名前空間の名前。
  • TABLE_NAME: テーブルの名前。

BigQuery でカタログ連携を使用する

Iceberg REST カタログ インターフェースを使用して、BigQuery に表示されるテーブルを管理し、クエリを実行できます。BigQuery 連携カタログでは、カタログ リソースを作成する必要はありません。BigQuery API が有効になっているプロジェクトで使用できます。この機能には次のような利点があります。

• BigQuery で外部 Iceberg テーブルを作成して管理します。
• Iceberg REST カタログを使用して、BigQuery 内の Apache Iceberg 用 BigLake テーブルのクエリを実行します。

これらのリソースは BigQuery によって管理されるため、該当する必要な権限が必要です。連携カタログでは認証情報のベンダーはサポートされていません。

フェデレーションを有効にするには、Iceberg REST カタログを使用するのクライアント構成例の WAREHOUSE_PATH フィールドで、bq://projects/PROJECT_ID ウェアハウス形式を使用してクライアントを構成します。bq://projects/PROJECT_ID/locations/LOCATION 形式を使用して BigQuery のロケーションを含め、今後のリクエストを単一のロケーションに制限することもできます。

連携用にクライアントを構成したら、連携テーブルの Namespace を作成できます。

Spark

BigQuery カタログ連携を使用するには、LOCATION 句と DBPROPERTIES 句を含めます。

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

次のように置き換えます。

• NAMESPACE_NAME: Namespace の名前。
• BUCKET_NAME: カタログで使用している Cloud Storage バケット。
• LOCATION: BigQuery のロケーション。デフォルト値は US マルチリージョンです。

Trino

BigQuery カタログ フェデレーションを使用するには、LOCATION プロパティと gcp-region プロパティを含めます。

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

次のように置き換えます。

• CATALOG_NAME: Iceberg REST カタログを使用する Trino カタログの名前。
• SCHEMA_NAME: スキーマの名前。
• BUCKET_NAME: カタログで使用している Cloud Storage バケット。
• LOCATION: BigQuery のロケーション。デフォルト値は US マルチリージョンです。

料金

料金の詳細については、BigLake の料金をご覧ください。

次のステップ

• Google Cloud コンソールでカタログを管理する方法を確認する。

• Apache Iceberg 用の BigLake テーブルについて学習する。