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 ランタイムカタログ内に作成された Iceberg カタログインスタンスをおすすめします。

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

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

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

始める前に

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

既存のバージョン 1（V1）の Apache Iceberg テーブルがある場合は、Apache Iceberg REST カタログエンドポイントで使用する前にアップグレードする必要があります。詳細については、Iceberg V1 テーブルを V2 にアップグレードするをご覧ください。

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 カタログにテーブルを登録する: プロジェクトに対する BigLake 管理者（roles/biglake.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 ランタイムカタログサービスアカウントを使用します。関連付けられたすべての Cloud Storage バケットに対する Storage オブジェクトユーザー（roles/storage.objectUser）。カタログを作成したら、関連付けられているすべてのストレージバケットに対する 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 フェデレーションテーブルが変更可能であるわけではありません。Iceberg マネージドテーブルでは DML は禁止されています）。
- プロジェクトに対する BigQuery データ編集者（roles/bigquery.dataEditor）
- 関連付けられているすべての Cloud Storage バケットに対するストレージ管理者（roles/storage.admin）。Managed Service for Apache Spark などのクエリエンジンを使用して DML オペレーションを実行する場合は、そのエンジンでジョブを実行するために使用するサービスアカウントにこれらのロールを付与します。

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

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

制限事項

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

一般的な制限事項

Apache Iceberg V2 テーブル（一般提供版）と V3 テーブル（プレビュー版）がサポートされています。Iceberg V1 テーブルはサポートされていません。Apache Iceberg REST カタログエンドポイントで既存の V1 テーブルを使用する前に、サポートされているバージョンにアップグレードする必要があります。
Trino は、Managed Service for Apache Spark on Compute Engine 2.3 イメージバージョン 2.3.16 以降を使用する場合にのみ、BigQuery カタログフェデレーションでサポートされます。
認証情報ベンディングモードを使用する場合は、io-impl プロパティを org.apache.iceberg.gcp.gcs.GCSFileIO に設定する必要があります。デフォルトの org.apache.iceberg.hadoop.HadoopFileIO はサポートされていません。
現在、階層型名前空間バケットは Credential Vending モードでサポートされていません。

テーブルの制限事項

BigQuery データ定義言語（DDL）ステートメントまたはデータ操作言語（DML）ステートメントを使用して、Apache Iceberg REST カタログエンドポイントでテーブルを作成または変更することはできません。これらのテーブルは BigQuery API（bq コマンドラインツールまたはクライアントライブラリを使用）を使用して変更できますが、外部エンジンと互換性のない変更が行われる可能性があります。
Apache Iceberg REST Catalog エンドポイントを介して管理されるテーブルは、行レベルや列レベルのセキュリティなどのきめ細かいアクセス制御（FGAC）をサポートしていません。
Iceberg テーブルのプロパティ write.data.path または write.metadata.path をデフォルト以外の値に設定することは禁止されています。
テーブルパスは、親 Namespace パス（gs://{namespace_path}/.../{table_name} など）内にネストする必要があります。競合を防ぎ、セキュリティを強化するため、結果のロケーション（gs://{namespace_path}/{table_name}/{random_suffix} など）にはランダムな文字列の接尾辞が自動的に付加されます。

データの上限

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

クエリの制限事項

Apache Iceberg メタデータテーブル（.snapshots や .files など）は、5 部構成の名前識別子を使用して BigQuery でクエリできません。これらのテーブルは Spark を使用してクエリできます。

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

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

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

Iceberg REST カタログのエンドポイントの概要に基づいて、カタログタイプを選択します。これは、マルチバケット（bl://）カタログ（推奨）またはシングルバケット（gs://）カタログを構成できます。
ウェアハウスのロケーションを参照するカタログを作成します。
Apache Iceberg REST カタログエンドポイントを使用するようにクライアントアプリケーションを構成します。
テーブルを整理するための Namespace またはスキーマを作成します。
構成したクライアントを使用してテーブルを作成し、クエリを実行します。

カタログを作成

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

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

考慮事項

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

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

エンドユーザー認証情報

コンソール

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

[Lakehouse] に移動
[カタログを作成] をクリックします。
[カタログのタイプ] で [Cloud Storage バケット] を選択します。
カタログで使用する Cloud Storage バケットを入力または参照します（単一バケット（gs://）カタログの場合、バケットごとに 1 つのカタログのみを使用でき、カタログ名はバケット名と一致します）。
[Authentication method] で [End-user credentials] を選択します。
[作成] をクリックします。

gcloud

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

マルチバケット（bl://）カタログを作成する（推奨）

マルチバケット（bl://）カタログを作成するには（推奨）、次のコマンドを実行します。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

単一バケット（gs://）カタログを作成する

単一バケット（gs://）カタログを作成するには、次のコマンドを実行します。

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

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

CATALOG_NAME: カタログの名前。マルチバケット（bl://）カタログ（推奨）の場合、これはカスタムカタログ名です。単一バケット（gs://）カタログの場合、これは REST カタログで使用される Cloud Storage バケット ID と一致します。この名前は、BigQuery からこれらのテーブルをクエリするときにカタログ識別子としても使用されます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
DEFAULT_LOCATION: カタログのデフォルトの保存場所を指定します。バケット（gs://my-bucket）またはサブパス（gs://my-bucket/path）を指定できます。カタログ内のすべての名前空間とテーブルは、指定されたパスの下に存在する必要があります。たとえば、gs://my-bucket/path を指定した場合、gs://my-bucket/another/path の下に Namespace やテーブルを作成することはできません。
RESTRICTED_LOCATIONS: （省略可）追加で許可する保存場所のカンマ区切りのリスト。gs://my-bucket-1/...,gs://my-bucket-2/... の形式で指定します。パス（gs://my-bucket/path など）を指定する場合、そのバケット内の名前空間またはテーブルは、そのパスの下にある必要があります。デフォルトのロケーションと制限付きロケーションにまたがるすべての構成済みクラウドストレージのロケーションは、同じ地理的リージョングループまたは法域（米国、ヨーロッパ、カナダ、アジアなど）に存在する必要があります。たとえば、米国のバケットとヨーロッパのバケットを混在させることはできません。サポートされているロケーションの一覧については、Lakehouse のロケーションをご覧ください。セキュリティに関する警告: 認証情報の不正な公開を防ぐため、他のカタログと重複するパスを構成しないでください。詳細については、複数のバケットにまたがるストレージをご覧ください。
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 などのツールを使用する場合は、このロールを手動で付与する必要があります。

コンソール

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

[Lakehouse] に移動
[ カタログを作成] をクリックします。[カタログの作成] ページが開きます。
[カタログのタイプ] で [Cloud Storage バケット] を選択します。
カタログで使用する Cloud Storage バケットを入力または参照します（単一バケット（gs://）カタログの場合、バケットごとに 1 つのカタログのみを使用でき、カタログ名はバケット名と一致します）。
[認証方法] で、[認証情報ベンダーモード] を選択します。
[作成] をクリックします。

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

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

gcloud

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

マルチバケット（bl://）カタログを作成する（推奨）

マルチバケット（bl://）カタログを作成するには（推奨）、次のコマンドを実行します。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

単一バケット（gs://）カタログを作成する

[!CAUTION] 以前のカタログタイプ。新しいプロジェクトでは、以前の単一バケット構成を使用することは強く推奨されません。この構成では、カタログが単一のバケットに制限され、カタログ名がバケット名にロックされます。

単一バケット（gs://）カタログを作成するには、次のコマンドを実行します。

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials

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

CATALOG_NAME: カタログの名前。マルチバケット（bl://）カタログ（推奨）の場合、これはカスタムカタログ名です。単一バケット（gs://）カタログの場合、これは REST カタログで使用される Cloud Storage バケット ID と一致します。この名前は、BigQuery からこれらのテーブルをクエリするときにカタログ識別子としても使用されます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
DEFAULT_LOCATION: カタログのデフォルトの保存場所を指定します。バケット（gs://my-bucket）またはサブパス（gs://my-bucket/path）を指定できます。カタログ内のすべての名前空間とテーブルは、指定されたパスの下に存在する必要があります。たとえば、gs://my-bucket/path を指定した場合、gs://my-bucket/another/path の下に Namespace やテーブルを作成することはできません。
RESTRICTED_LOCATIONS: （省略可）追加で許可する保存場所のカンマ区切りのリスト。gs://my-bucket-1/...,gs://my-bucket-2/... の形式で指定します。パス（gs://my-bucket/path など）を指定する場合、そのバケット内の名前空間またはテーブルは、そのパスの下にある必要があります。デフォルトのロケーションと制限付きロケーションにまたがるすべての構成済みクラウドストレージのロケーションは、同じ地理的リージョングループまたは法域（米国、ヨーロッパ、カナダ、アジアなど）に存在する必要があります。たとえば、米国のバケットとヨーロッパのバケットを混在させることはできません。サポートされているロケーションの一覧については、Lakehouse のロケーションをご覧ください。セキュリティに関する警告: 認証情報の不正な公開を防ぐため、他のカタログと重複するパスを構成しないでください。詳細については、複数のバケットにまたがるストレージをご覧ください。
LOCATION: （省略可）BigQuery との相互運用性を確保するためのカタログのプライマリリージョン。米国リージョン（US や us-central1 など）または EU リージョン（EU や europe-west4 など）の Cloud Storage バケットの場合は、それぞれ US または EU を指定して、対応する BigQuery マルチリージョンからカタログにアクセスしてクエリを実行できるようにします。詳細については、バケットとカタログのリージョンをご覧ください。

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

カタログをアップグレードする

既存の単一バケット（gs://）カタログがある場合は、マルチバケット（bl://）カタログタイプにアップグレードできます（推奨）。アップグレードすると、複数のバケットを関連付け、制限付きのロケーションを構成しながら、元のカタログ名を保持できます。

カタログをアップグレードするには、カタログを更新するをご覧ください。

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

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

クラスタ

簡略化された構成プロパティを使用するか（推奨）、プロパティを手動で指定して、Managed Service for Apache Spark on Compute Engine クラスタを作成します。

プロパティを使用した簡略化された構成（推奨）

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

gcloud dataproc clusters create CLUSTER_NAME \
  --enable-component-gateway \
  --project=PROJECT_ID \
  --region=REGION \
  --optional-components=ICEBERG \
  --image-version=DATAPROC_VERSION \
  --properties="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.3）。
CATALOG_NAME: ローカル Spark カタログの名前（例: my_catalog）。CATALOG_ID と同じ値にすることもできます。
CATALOG_ID: 作成したカタログの ID。

PySpark アプリケーションファイルで、カタログ構成を指定せずに SparkSession を作成します。

from pyspark.sql import SparkSession

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

手動設定

簡略化された構成プロパティを使用しない場合は、上記の説明に沿って --properties フラグなしでクラスタを作成します。次に、SparkSession を手動で構成します。

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_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') \
  .getOrCreate()

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

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

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

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

.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('spark.sql.defaultCatalog', 'CATALOG_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(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

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

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

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

サーバーレス

簡略化された構成プロパティを使用するか（推奨）、プロパティを手動で指定して、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"

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

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.3）。
CATALOG_NAME: ローカル Spark カタログの名前（例: my_catalog）。CATALOG_ID と同じ値にすることもできます。
CATALOG_ID: 作成したカタログの ID。

PySpark アプリケーションファイルで、カタログ構成を指定せずに SparkSession を作成します。

from pyspark.sql import SparkSession

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

手動設定

簡略化された構成プロパティを使用しない場合は、カタログ構成を手動で指定する必要があります。

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.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

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

PYSPARK_FILE: PySpark アプリケーションファイルの gs:// Cloud Storage パス。
REGION: Managed Service for Apache Spark バッチワークロードのリージョン。
RUNTIME_VERSION: Managed Service for Apache Spark のランタイムバージョン（例: 2.3）。
CATALOG_NAME: ローカル Spark カタログの名前（例: my_catalog）。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスのパス。BigLake カタログの場合は、bl://projects/PROJECT_ID/catalogs/CATALOG_ID を使用します。Cloud Storage バケットカタログの場合は、gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログフェデレーションを使用するには、BigQuery でカタログフェデレーションを使用するをご覧ください。
PROJECT_ID: Apache Iceberg REST カタログエンドポイントの使用に対して課金されるプロジェクト。Cloud Storage バケットを所有するプロジェクトとは異なる場合があります。REST API を使用する場合のプロジェクト構成の詳細については、システムパラメータをご覧ください。

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

認証情報ベンダーを使用するには、認証情報ベンダーモードのカタログを使用し、次の行を 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=WAREHOUSE_PATH,\
    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.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

詳細については、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: ウェアハウスのパス。BigLake カタログの場合は、bl://projects/PROJECT_ID/catalogs/CATALOG_ID を使用します。Cloud Storage バケットカタログの場合は、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 認可フローをサポートしています。

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

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

認証情報のベンディングは、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: ローカル Spark カタログの名前（例: my_catalog）。
APP_NAME: Spark セッションの名前。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスのパス。BigLake カタログの場合は、bl://projects/PROJECT_ID/catalogs/CATALOG_ID を使用します。Cloud Storage バケットカタログの場合は、gs://CLOUD_STORAGE_BUCKET_NAME を使用します。BigQuery カタログフェデレーションを使用するには、BigQuery でカタログフェデレーションを使用するをご覧ください。
PROJECT_ID: Apache Iceberg REST カタログエンドポイントの使用に対して課金されるプロジェクト。Cloud Storage バケットを所有するプロジェクトとは異なる場合があります。REST API を使用する場合のプロジェクト構成の詳細については、システムパラメータをご覧ください。

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

上記の例では、認証情報のベンディングは使用されていません。認証情報ベンディングを使用するには、認証情報ベンディングモードのカタログを使用し、次の行を SparkSession ビルダーに追加して、Apache 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/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(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: ローカル Spark カタログの名前（例: my_catalog）。
APP_NAME: Spark セッションの名前。
REST_API_VERSION: API の安定版の場合は v1 に設定します。
WAREHOUSE_PATH: ウェアハウスのパス。BigLake カタログの場合は、bl://projects/PROJECT_ID/catalogs/CATALOG_ID を使用します。Cloud Storage バケットカタログの場合は、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', '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}.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 を使用して作成する方法を示しています。

コンソール

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

[レイクハウス] に移動
既存のカタログを選択するか、カタログがない場合は作成します。
メニューバーで、[+ Namespace を作成] をクリックします。
[Namespace name] に、Namespace の一意の名前を入力します。
[ロケーション] に、Namespace に関連付けるパスを指定します。
- マルチバケット（bl://）（推奨）: カタログ（default_location または restricted_locations）で許可されているロケーションの下にある限り、任意のカスタムロケーションを設定できます。ロケーションを指定しない場合、名前空間はカタログのデフォルトのロケーション（gs://{path-to-default-location}/{namespace_name} など）の下に作成されます。マルチバケット（bl://）カタログ（推奨）はコンソールで管理できません。
- single-bucket（gs://）: 名前空間のロケーションは、カタログの単一バケットから自動的に継承されます。
[作成] をクリックします。

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 カタログを設定する

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

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

Cloud Storage データウェアハウス

Cloud Storage データウェアハウス