2026 年 4 月 20 日より、BigLake は Lakehouse for Apache Iceberg に名称変更されました。BigLake metastore は、Lakehouse ランタイムカタログと呼ばれるようになりました。Lakehouse API、クライアントライブラリ、CLI コマンド、IAM 名は変更されず、引き続き BigLake を参照します。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Lakehouse Iceberg REST カタログを設定する

新しいワークフローでは、 Lakehouse ランタイムカタログ内の Apache Iceberg REST カタログエンドポイントを使用することをおすすめします。

このエンドポイントは信頼できる唯一の情報源として機能し、クエリエンジン間のシームレスな相互運用を可能にします。これにより、Apache Spark などのエンジンは、Google Cloud Lakehouse テーブルを検出、読み取り、管理できます。

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

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

始める前に

続行する前に、Lakehouse ランタイムカタログと Iceberg REST カタログエンドポイントの概要をよく理解してください。

プロジェクト Google Cloud に対して課金が有効になっていることを確認します。
BigLake API を有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。
API の有効化

必要なロール

Lakehouse ランタイムカタログで Apache Iceberg REST カタログエンドポイントを使用するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

カタログユーザーアクセス、ストレージアクセス、カタログの認証情報ベンディングモードの管理などの管理タスクを実行する:
- BigLake 管理者（roles/biglake.admin）プロジェクトに対する
- Cloud Storage バケットに対するストレージ管理者 (roles/storage.admin)
認証情報ベンディングモードでテーブルデータを読み取る: BigLake 閲覧者 (roles/biglake.viewer) プロジェクトに対する。Managed Service for Apache Spark、Managed Service for Apache Spark、Dataflow などのクエリエンジンを使用してテーブルデータを読み取る場合は、そのエンジンでジョブを実行するために使用するサービスアカウントにこのロールを付与します。
認証情報ベンディングモードでテーブルデータを書き込む: BigLake 編集者（roles/biglake.editor） : プロジェクトに対する。Managed Service for Apache Spark、Managed Service for Apache Spark、Dataflow などのクエリエンジンを使用してテーブルデータを書き込む場合は、そのエンジンでジョブを実行するために使用するサービスアカウントにこのロールを付与します。
認証情報ベンディングモードで自動プロビジョニングされた Lakehouse ランタイムカタログサービスアカウントを使用する: Storage オブジェクトユーザー（roles/storage.objectUser）ターゲット Cloud Storage バケットに対する。カタログを作成したら、ストレージバケットに対する Storage オブジェクトユーザーロール（roles/storage.objectUser）を、カタログの自動プロビジョニングされた Lakehouse ランタイムカタログサービスアカウントに明示的に付与します。
認証情報ベンディングモード以外でカタログリソースとテーブルデータを読み取る:
- プロジェクトに対する 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 オペレーションを実行する場合は、そのエンジンでジョブを実行するために使用するサービスアカウントにこれらのロールを付与します。

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

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

制限事項

Apache Iceberg REST カタログエンドポイントには次の制限があります。

一般的な制限事項

Iceberg V2 テーブルのみがサポートされています。Iceberg V1 テーブルはサポートされていません。既存の Iceberg V1 テーブルがある場合は、Apache Iceberg REST カタログエンドポイントで使用する前に、V2 にアップグレードする必要があります（ALTER TABLE catalog.schema.table SET TBLPROPERTIES ('format-version'='2'); を実行するか、同様のエンジンオペレーションを使用します）。
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 はサポートされていません。

テーブルの制限事項

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

データの制限事項

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

クエリの制限事項

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

Iceberg REST カタログエンドポイントを設定する

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

Lakehouse ランタイムカタログで Apache Iceberg REST カタログエンドポイントを使用する一般的な手順は次のとおりです。

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

カタログを作成

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

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

考慮事項

カタログを作成する前に、ロケーションの要件をよく理解してください。

Namespace を作成すると、カタログと同じリージョンが自動的に使用されます。
カタログでマルチリージョンバケットを使用し、BigQuery マルチリージョン（US または EU）で使用する場合は、カタログを削除して再作成し、プライマリロケーションを指定する必要があります。

エンドユーザー認証情報

コンソール

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

[Lakehouse] に移動
[カタログを作成] をクリックします。
[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: カタログの名前。Lakehouse ランタイムカタログでサポートされている Apache Iceberg テーブルの場合、この名前は REST カタログで使用される Cloud Storage バケット ID と一致することがよくあります。たとえば、バケットが gs://bucket-id の場合、カタログ名は bucket-id になります。この名前は、カタログ識別子としても使用されます。BigQuery からこれらのテーブルにクエリを実行するときに、これらのテーブルにクエリを実行するときに、
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: （省略可）BigQuery との相互運用性を確保するためのカタログのプライマリリージョン。米国リージョン（US や us-central1 など）または EU リージョン（EU やeurope-west4 など）の Cloud Storage バケットの場合は、 US または EU を指定して、カタログにアクセスして対応する BigQuery マルチリージョンからクエリを実行できるようにします。詳細については、バケットとカタログのリージョンをご覧ください。

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

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

自動プロビジョニングされた Lakehouse ランタイムカタログサービスアカウントには、ターゲット Cloud Storage バケットに対する明示的な Storage オブジェクトユーザーロール（roles/storage.objectUser）が必要です。デフォルトでは、閲覧者のみのアクセス権で作成されます。このロールがないと、ベンディングされた認証情報のスコープが不足し、ストレージへの書き込みを実行できません。gcloud や Terraform などのツールを使用する場合は、このロールを手動で付与する必要があります。

コンソール

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

[Lakehouse] に移動
[Create catalog] をクリックします。[カタログを作成] ページが開きます。
[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 vended-credentials \
    [--primary-location LOCATION]

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

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

カタログを作成したら、ストレージバケットに対する Storage オブジェクトユーザー ロール（roles/storage.objectUser）を、カタログの自動プロビジョニングされた Lakehouse ランタイムカタログサービスアカウントに明示的に付与します。

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

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

クラスタ

Managed Service for Apache Spark の Apache Iceberg REST カタログエンドポイントで Spark を使用するには、プロパティを使用して構成を簡素化するか、セッションを手動で構成します。

プロパティを使用した構成の簡素化（推奨）

カタログプロパティを使用してクラスタを作成します。

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

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

CLUSTER_NAME: クラスタの名前。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
REGION: Managed Service for Apache Spark クラスタリージョン。
DATAPROC_VERSION: Managed Service for Apache Spark イメージバージョン（2.2 など）。
CATALOG_NAME: Spark で使用する Lakehouse カタログの名前。CATALOG_ID と同じにできます。
CATALOG_ID: 作成した Lakehouse カタログの ID。

次に、カタログパラメータを手動で指定せずに Spark セッションを作成します。

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

手動設定

クラスタプロパティを使用しない場合は、上記の説明に沿ってクラスタを作成し（--properties フラグなし）、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/REST_API_VERSION/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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

CATALOG_NAME: Apache Iceberg REST カタログエンドポイントの名前。
APP_NAME: Spark セッションの名前。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスへのパス。 gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログフェデレーションを使用するには、 BigQuery でカタログフェデレーションを使用するをご覧ください。
PROJECT_ID: Apache 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/REST_API_VERSION/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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

Managed Service for Apache Spark クラスタは、次のリリースで Apache 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="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

手動設定

すべてのプロパティを手動で指定する場合は、次の構成を使用します。

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/REST_API_VERSION/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"

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

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: Apache Iceberg REST カタログエンドポイントの名前。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスへのパス。 gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログ連携を使用するには、 BigQuery でカタログ連携を使用するをご覧ください。

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

認証情報ベンディングを使用するには、認証情報ベンディングモードでカタログを使用し、Managed Service for Apache Spark 構成に次の行を追加して、値がvended-credentialsの X-Iceberg-Access-Delegationヘッダーを Apache 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/REST_API_VERSION/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.header.X-Iceberg-Access-Delegation=vended-credentials"

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

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

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

Trino

Apache 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/REST_API_VERSION/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: Apache Iceberg REST カタログエンドポイントを使用する Trino カタログの名前。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスへのパス。 gs://CLOUD_STORAGE_BUCKET_NAME を使用します。
PROJECT_ID: Lakehouse ランタイムカタログで使用する実際の Google Cloud プロジェクト ID 。

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

trino --catalog=CATALOG_NAME

Managed Service for Apache Spark Trino は、次のリリースで Apache 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 はサポートされていません。

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

認証情報ベンディングは、Trino バージョン 481 以降でのみサポートされています。

Apache Iceberg 1.10 以降

オープンソースの Apache Iceberg 1.10 以降のリリースには、GoogleAuthManager で Google 認証フローのサポートが組み込まれています。次の例は、Apache 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/REST_API_VERSION/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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

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

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

上記の例では、認証情報ベンディングは使用されていません。認証情報ベンディングを使用するには、認証情報ベンディングモードでカタログを使用し、`SparkSession` ビルダーに次の行を追加して、値が `vended-credentials` の `X-Iceberg-Access-Delegation` ヘッダーを Apache 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/REST_API_VERSION/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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

以前の Apache Iceberg リリース

1.10 より前のオープンソース Apache 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/REST_API_VERSION/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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

CATALOG_NAME: Apache Iceberg REST カタログエンドポイントの名前。
APP_NAME: Spark セッションの名前。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスへのパス。 gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログフェデレーションを使用するには、 BigQuery でカタログフェデレーションを使用するをご覧ください。
PROJECT_ID: Apache 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/REST_API_VERSION/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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

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

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

コンソール

コンソールで、[Lakehouse] に移動します。 Google Cloud

[Lakehouse] に移動
既存のカタログを選択するか、カタログがない場合は作成します。
メニューバーで、[+ Namespace を作成] をクリックします。
[**Namespace 名**] に、Namespace の一意の名前を入力します。
[**ロケーション**] で、 Namespace に関連付ける Cloud Storage バケットを選択します。
[作成] をクリックします。

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: Apache Iceberg REST カタログエンドポイントを使用する Trino カタログの名前。
SCHEMA_NAME: スキーマの名前。

次のステップ

テーブルにクエリを実行して、BigQuery でカタログフェデレーションを使用する方法を学習する。
コンソールでカタログを管理する方法を確認する。 Google Cloud
Apache Iceberg 用の Lakehouse REST カタログテーブルについて学習する。

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

始める前に

必要なロール

制限事項

Iceberg REST カタログ エンドポイントを設定する

カタログを作成

エンドユーザー認証情報

コンソール

gcloud

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

コンソール

gcloud

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

クラスタ

プロパティを使用した構成の簡素化（推奨）

手動設定

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

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

サーバーレス

プロパティを使用した構成の簡素化（推奨）

手動設定

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

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

Trino

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

Apache Iceberg 1.10 以降

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

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

以前の Apache Iceberg リリース

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

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

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

コンソール

Spark

Cloud Storage ウェアハウス

Trino

Cloud Storage ウェアハウス

次のステップ

Lakehouse Iceberg REST カタログを設定する

Iceberg REST カタログエンドポイントを設定する

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

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