このページは Cloud Translation API によって翻訳されました。

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

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

Iceberg REST カタログで使用する Iceberg テーブルは、Apache Iceberg 用 BigLake テーブル（プレビュー）と呼ばれます。これらは、オープンソースエンジンから作成して Cloud Storage に保存する Iceberg テーブルです。これは、オープンソースエンジンまたは BigQuery で読み取ることができます。書き込みはオープンソースエンジンからのみサポートされます。このドキュメントでは、これらのテーブルを BigLake Iceberg テーブルと呼びます。

始める前に

Verify that billing is enabled for your Google Cloud project.
詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
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 の仕組みと使用すべき理由を理解します。

必要なロール

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）

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

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

認証情報ベンディングモードを設定する

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

カタログ管理者が Iceberg REST カタログクライアントで認証情報のベンディングを有効にします。

カタログユーザーは、Iceberg REST カタログ API 仕様の一部であるアクセス委任を指定して、範囲が限定されたストレージ認証情報を返すように Iceberg REST カタログに指示できます。詳細については、Iceberg REST カタログを使用してクエリエンジンを構成するをご覧ください。

カタログを初期化して認証情報ベンディングモードを有効にするには、次の手順を行います。

次のコマンドでカタログを初期化します。

curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
CLOUD_STORAGE_BUCKET_NAME: Iceberg テーブルを保存する Cloud Storage バケットの名前。

curl コマンドの出力は、次のようになります。カタログの接頭辞の値は、レスポンスの overrides.prefix フィールドにあります。

{
  "overrides": {
    "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
    "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
  },
  "endpoints": [
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}",
    "HEAD /v1/{prefix}/namespaces/{namespace}",
    "DELETE /v1/{prefix}/namespaces/{namespace}",
    "POST /v1/{prefix}/namespaces/{namespace}/properties",
    "GET /v1/{prefix}/namespaces/{namespace}/tables",
    "POST /v1/{prefix}/namespaces/{namespace}/tables",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
  ]
}

次のコマンドを使用して、認証情報ベンダーモードを有効にし、権限を付与するサービスアカウントを抽出します。

curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

PREFIX は、前のコマンドの出力の prefix フィールドに置き換えます。

curl コマンドの出力には、次のようなサービスアカウントが含まれます。

{
  "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
  "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
  "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
}

前の手順で抽出した BigLake サービスアカウントに、認証情報ベンディングモードを使用するために必要な権限があることを確認するには、ストレージバケットに対するストレージオブジェクトユーザー（roles/storage.objectUser）ロールを付与するよう管理者に依頼してください。

重要: このロールは、ユーザーアカウントではなく、前の手順で抽出した BigLake サービスアカウントに付与する必要があります。正しいプリンシパルにロールを付与しないと、権限エラーが発生する可能性があります。

制限事項

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

マルチリージョンバケット、デュアルリージョンバケット、カスタムリージョンに配置されたバケットはサポートされていません。
認証情報ベンディングモードを使用する場合は、io-impl プロパティを org.apache.iceberg.gcp.gcs.GCSFileIO に設定する必要があります。デフォルトの org.apache.iceberg.hadoop.HadoopFileIO はサポートされていません。

Iceberg REST カタログを構成する

クラスタ

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', '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}.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 セッションの名前。
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg テーブルを保存する Cloud Storage バケットの名前。
PROJECT_ID: 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(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 以降。

サーバーレス

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

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"

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

PYSPARK_FILE: PySpark アプリケーションファイルの gs:// Cloud Storage パス。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
REGION: Dataproc バッチワークロードのリージョン。
RUNTIME_VERSION: Apache Spark 用 Serverless のランタイムバージョン（例: 2.2）。
CATALOG_NAME: Iceberg REST カタログの名前。
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg テーブルを保存する Cloud Storage バケットの名前。

認証情報ベンディングを使用するには、Apache Spark 向け Serverless 構成に次の行を追加して、値が 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.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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

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

Apache Spark 2.2 ランタイム 2.2.60 以降向け Serverless
Apache Spark 2.3 ランタイム 2.3.10 以降向け Serverless

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=gs://CLOUD_STORAGE_BUCKET_NAME,\
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 カタログの名前。
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg テーブルを保存する Cloud Storage バケットの名前。
PROJECT_ID: BigLake metastore に使用する Google Cloud プロジェクト ID。

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

trino

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

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

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', '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}.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 セッションの名前。
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg テーブルを保存する Cloud Storage バケットの名前。
PROJECT_ID: 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(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', '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}.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 セッションの名前。
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg テーブルを保存する Cloud Storage バケットの名前。
PROJECT_ID: Iceberg REST カタログの使用に対して課金されるプロジェクト。Cloud Storage バケットを所有するプロジェクトとは異なる場合があります。REST API を使用する場合のプロジェクト構成の詳細については、システムパラメータをご覧ください。
TOKEN: 1 時間有効な認証トークン（gcloud auth application-default print-access-token を使用して生成されたトークンなど）。

上記の例では、認証情報のベンディングは使用されていません。認証情報ベンディングを使用するには、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.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', '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 のヘッダーをご覧ください。

名前空間の作成

Spark

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

spark.sql("USE NAMESPACE_NAME;")

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

Trino

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

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

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

テーブルを作成する

Spark

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

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

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

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

TABLE_NAME は、テーブルの名前に置き換えます。

テーブルのリスト表示

Spark

spark.sql("SHOW TABLES").show()

Trino

SHOW TABLES;

テーブルにデータを挿入する

次の例では、テーブルにサンプルデータを挿入します。

Spark

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

テーブルに対してクエリを実行する

次の例では、テーブルからすべてのデータを選択します。

Spark

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino

SELECT * FROM TABLE_NAME;

次の例では、BigQuery から同じテーブルをクエリします。

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

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

CLOUD_STORAGE_BUCKET_NAME: Iceberg REST カタログの Cloud Storage バケットの名前。たとえば、URI が gs://iceberg_bucket の場合は、iceberg_bucket を使用します。
NAMESPACE_OR_SCHEMA_NAME: Spark を使用している場合はテーブル名前空間、Trino を使用している場合はテーブルスキーマ名。
TABLE_NAME: テーブルの名前。

テーブルスキーマを変更する

次の例では、テーブルに列を追加します。

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

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

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

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

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

SCHEMA_NAME: スキーマの名前
TABLE_NAME: テーブルの名前。

テーブルを削除する

次の例では、指定された名前空間からテーブルを削除します。

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

料金

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

次のステップ

BigLake Metastore を使用して Iceberg リソースを管理する方法について確認する。
BigLake Metastore の追加機能について確認する。

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

始める前に

必要なロール

認証情報ベンディング モードを設定する

制限事項

Iceberg REST カタログを構成する

クラスタ

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

サーバーレス

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

Trino

Iceberg 1.10 以降

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

以前の Iceberg リリース

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

名前空間の作成

Spark

Trino

テーブルを作成する

Spark

Trino

テーブルのリスト表示

Spark

Trino

テーブルにデータを挿入する

Spark

Trino

テーブルに対してクエリを実行する

Spark

Trino

テーブル スキーマを変更する

Spark

Trino

テーブルを削除する

Spark

Trino

料金

次のステップ

認証情報ベンディングモードを設定する

テーブルスキーマを変更する