テーブルを登録する

既存の Apache Iceberg テーブルを登録すると、そのメタデータがレイクハウス ランタイム カタログに統合され、テーブルデータが名前空間内でクエリと管理に使用できるようになります。このプロセスは、新しい空のテーブル構造とその関連ストレージを初期化するテーブル作成とは異なります。

始める前に

  1. Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

  2. BigLake API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

    API の有効化

  3. Apache Iceberg REST カタログのエンドポイントを使用して、Lakehouse ランタイム カタログを設定します。

必要なロール

テーブルの登録に必要な権限を取得するには、プロジェクトとストレージ バケットに対する次の IAM ロールを付与するよう管理者に依頼してください。

  • テーブルを登録します。
    • BigLake 管理者（roles/biglake.admin）- プロジェクト
    • ストレージ管理者（roles/storage.admin） - ターゲット Cloud Storage バケット

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

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

テーブルを登録する

既存の Iceberg テーブルを登録する。

gcloud

gcloud を使用してテーブルを登録するには、gcloud biglake iceberg tables register コマンドを実行します。

gcloud biglake iceberg tables register TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --metadata-location="METADATA_LOCATION" \
    [--overwrite]

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

  • TABLE_NAME: 登録済みテーブルに割り当てる名前。
  • PROJECT_ID: Google Cloud プロジェクト ID。
  • CATALOG_ID: カタログ ID。
  • NAMESPACE_NAME: カタログの Namespace 名。
  • METADATA_LOCATION: テーブルの最新のメタデータ JSON ファイルの Cloud Storage URI（例: gs://my-bucket/path/to/metadata/00001.metadata.json）。
  • --overwrite: （省略可）テーブルがすでに存在する場合は上書きします。

REST

REST API を使用して Iceberg テーブルを登録するには、RegisterIcebergTable エンドポイントに POST リクエストを行います。

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/register

リクエストの本文には、次の構造の JSON ペイロードを含める必要があります。

{
  "name": "TABLE_NAME",
  "metadata-location": "METADATA_LOCATION",
  "overwrite": OVERWRITE
}

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

  • PROJECT_ID: Google Cloud プロジェクト ID。
  • CATALOG_ID: カタログ ID。
  • NAMESPACE_NAME: カタログの Namespace 名。
  • TABLE_NAME: 登録済みテーブルの名前。
  • METADATA_LOCATION: テーブルの最新のメタデータ JSON ファイルの Cloud Storage URI。
  • OVERWRITE: テーブルが存在する場合は true、存在しない場合は false。

次のステップ