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

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

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

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

始める前に

続行する前に、BigLake metastore と Iceberg REST カタログの概要をよく理解してください。

プロジェクト Google Cloud に対して課金が有効になっていることを確認します。
BigLake API を有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。
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）
BigQuery カタログフェデレーションでデータ操作言語（DML）オペレーションを実行する:
- プロジェクトに対する BigQuery データ編集者（roles/bigquery.dataEditor）
- Cloud Storage バケットに対するストレージ管理者（roles/storage.admin）。Managed Service for Apache Spark などのクエリエンジンを使用して DML オペレーションを実行する場合は、そのエンジンでジョブを実行するために使用するサービスアカウントにこれらのロールを付与します。

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

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

制限事項

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

一般的な制限事項

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

テーブルの制限事項

REST カタログで管理されるテーブルは、行レベルや列レベルのセキュリティなどのきめ細かいアクセス制御（FGAC）をサポートしていません。

データの制限事項

Parquet ファイルのみがサポートされています。BigQuery で Parquet ファイルを処理する方法の詳細については、Cloud Storage からの Parquet データの読み込みをご覧ください。
Iceberg metadata.json ファイルのサイズは 1 MB に制限されています。この上限の引き上げをリクエストするには、Google アカウントチームにお問い合わせください。

クエリの制限事項

REST カタログで管理される Iceberg テーブルのビューは、BigQuery で作成できません。
Iceberg メタデータテーブル（.snapshots や .files など）は、5 つの部分からなる名前識別子を使用して BigQuery でクエリできません。これらのテーブルは Spark を使用してクエリできます。

Iceberg REST カタログを設定する

カタログを設定する前に、Iceberg REST カタログの概要を読んで、リソース階層、カタログタイプ、命名構造を理解することをおすすめします。

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

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

カタログを作成

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

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

エンドユーザー認証情報

コンソール

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

BigLake に移動
[カタログを作成] をクリックします。
[Cloud Storage バケットを選択] フィールドに、カタログで使用する Cloud Storage バケットの名前を入力します。または、[参照] をクリックして、既存のバケットを選択するか、新しいバケットを作成します。Cloud Storage バケットごとに 1 つのカタログのみを使用できます。
[**認証方法**] で [**エンドユーザー認証情報**] を選択します。
[作成] をクリックします。

gcloud

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

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

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

CATALOG_NAME: カタログの名前。Apache Iceberg 用のマネージド BigLake テーブルの場合、この名前は REST カタログで使用される Cloud Storage バケット ID と一致することがよくあります。たとえば、バケットが gs://bucket-id の場合、カタログ名は bucket-id になります。この名前は、カタログ識別子としても使用されます。BigQuery からこれらのテーブルにクエリを実行するときに、これらのテーブルにクエリを実行するときに、
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: 省略可。カタログのプライマリリージョン。 Cloud Storage の米国または EU のマルチリージョンバケットの場合は、US または EU を指定して、対応する BigQuery リージョンからカタログにアクセスできるようにします。詳細については、カタログリージョンをご覧ください。

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

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

コンソール

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

BigLake に移動
[Create catalog] をクリックします。[カタログを作成] ページが開きます。
[Cloud Storage バケットを選択] に、カタログで使用する Cloud Storage バケットの名前を入力します。または、[参照] をクリックして、既存のバケットのリストから選択するか、新しいバケットを作成します。Cloud Storage バケットごとに 1 つのカタログのみを使用できます。
[**認証方法**] で [**認証情報ベンディングモード**] を選択します。
[作成] をクリックします。

カタログが作成され、[カタログの詳細] ページが開きます。
[認証方法] で [バケットの権限を設定] をクリックします。
ダイアログで [確認] をクリックします。

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

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

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

クラスタ

Managed Service for Apache Spark の 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: Managed Service for Apache Spark クラスタのリージョン。
DATAPROC_VERSION: Managed Service for Apache Spark イメージバージョン（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 を使用する場合のプロジェクト構成の詳細については、システムパラメータをご覧ください。

認証情報ベンディングを使用して構成する

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

.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

Managed Service for Apache Spark クラスタは、次のリリースで Iceberg の Google 認可フローをサポートしています。

Compute Engine 2.2 イメージバージョン 2.2.65 以降の Managed Service for Apache Spark。
Compute Engine 2.3 イメージバージョン 2.3.11 以降の Managed Service for Apache Spark。

サーバーレス

次の構成で PySpark バッチワークロードを Managed Service for Apache Spark に送信します。

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: Managed Service for Apache Spark バッチワークロードのリージョン。
RUNTIME_VERSION: Managed Service for Apache Spark ランタイムバージョン（2.2 など）。
CATALOG_NAME: Iceberg REST カタログの名前。
WAREHOUSE_PATH: ウェアハウスへのパス。gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログ連携を使用するには、 BigQuery でカタログ連携を使用するをご覧ください。

認証情報ベンディングを使用して構成する

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

.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.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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

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

Managed Service for Apache Spark 2.2 ランタイム 2.2.60 以降
Managed Service for Apache Spark 2.3 ランタイム 2.3.10 以降

Trino

Iceberg REST カタログで Trino を使用するには、Trino コンポーネントを含む Managed Service for Apache Spark クラスタを作成し、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: Managed Service for Apache Spark クラスタリージョン。
DATAPROC_VERSION: Managed Service for Apache Spark イメージバージョン（2.2 など）。
NETWORK_ID: クラスタネットワーク ID。詳細については、Managed Service for Apache Spark クラスタネットワーク構成をご覧ください。
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

Managed Service for Apache Spark Trino は、次のリリースで Iceberg の Google 認可フローをサポートしています。

Compute Engine 2.2 ランタイムバージョン 2.2.65 以降の Managed Service for Apache Spark。
Compute Engine 2.3 ランタイムバージョン 2.3.11 以降の Managed Service for Apache Spark。
Compute Engine 3.0 の Managed Service for Apache Spark はサポートされていません。

認証情報ベンディングを使用して構成する

Managed Service for Apache Spark Trino では、認証情報ベンディングはサポートされていません。

Iceberg 1.10 以降

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

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` ビルダーに次の行を追加して、値が `vended-credentials` の `X-Iceberg-Access-Delegation` ヘッダーを Iceberg REST カタログリクエストに追加する必要があります。X-Iceberg-Access-Delegationvended-credentialsSparkSession

.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 を使用して生成されたトークンです。

認証情報ベンディングを使用して構成する

.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 を使用して作成する方法を示します。

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 バケットウェアハウス: クライアントをウェアハウスパスで構成した場合は、4 つの部分からなる名前（P.C.N.T）project.catalog.namespace.table を使用して BigQuery からテーブルにクエリを実行します。gs://P.C.N.T 構造の詳細については、Iceberg REST カタログのコンセプトをご覧ください。 catalog コンポーネントは、BigLake metastore カタログリソースの名前です。テーブルのクエリの詳細については、テーブルにクエリを実行するをご覧ください。
BigQuery フェデレーション: クライアントを bq:// ウェアハウスパスで構成した場合、作成したテーブルは BigQuery に表示され、標準の BigQuery SQL を使用して直接クエリできます。
```
SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;
```
次のように置き換えます。
- NAMESPACE_NAME: Namespace の名前。
- TABLE_NAME: テーブルの名前。

BigQuery でカタログフェデレーションを使用する

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

これらのリソースは BigQuery によって管理されるため、該当する必要な権限が必要です。

フェデレーション用にクライアントを構成したら、フェデレーションテーブルの名前空間を作成できます。

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 テーブルについて確認する。

BigLake metastore Iceberg REST カタログを使用する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

制限事項

Iceberg REST カタログを設定する

カタログを作成

エンドユーザー認証情報

コンソール

gcloud

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

コンソール

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

クラスタ

認証情報ベンディングを使用して構成する

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

サーバーレス

認証情報ベンディングを使用して構成する

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

Trino

認証情報ベンディングを使用して構成する

Iceberg 1.10 以降

認証情報ベンディングを使用して構成する

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

以前の Iceberg リリース

認証情報ベンディングを使用して構成する

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

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

Spark

Cloud Storage ウェアハウス

Trino

Cloud Storage ウェアハウス

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

BigQuery でカタログ フェデレーションを使用する

Spark

Trino

料金

次のステップ

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

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

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

BigQuery でカタログフェデレーションを使用する