カタログを作成

Lakehouse ランタイム カタログを使用すると、ボーダーレス Lakehouse にカタログ エンドポイントを作成できます。

カタログ エンドポイントは、基盤となる Cloud Storage バケットを指し、クエリエンジンとオープンソース ワークロードがテーブルと直接やり取りできるメタデータ レイヤを提供します。カタログ エンドポイントを作成するときに、ストレージ アクセスの委任にエンドユーザー認証情報と認証情報ベンディング モードのいずれかを選択できます。

始める前に

  1. Lakehouse ランタイム カタログについてを読んで、Lakehouse ランタイム カタログの仕組みとサービスの制限事項を確認します。
    2. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分も差し上げます。

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

必要なロール

カタログの作成とテーブルの登録に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • カタログを作成します。
  • テーブルを作成（登録）する: プロジェクトに対する BigLake 管理者 （roles/biglake.admin）。テーブルを登録するには、特定のテーブル登録権限（biglake.tables.register）が必要です。この権限は BigLake 管理者ロールに含まれています。
  • 認証情報提供モードで自動プロビジョニングされたカタログ サービス アカウントを使用します。ターゲット Cloud Storage バケットに対する Storage オブジェクト ユーザー （roles/storage.objectUser）。カタログを作成したら、ストレージ バケットに対する Storage オブジェクト ユーザーロール（roles/storage.objectUser）を自動プロビジョニングされたサービス アカウントに明示的に付与します。

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

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

カタログを作成する

優先する認証情報モードとバケットタイプに基づいてカタログを作成する手順は次のとおりです。さまざまなカタログタイプの詳細については、Apache Iceberg REST カタログ エンドポイントについてをご覧ください。

コンソール

複数バケット カタログを作成する（推奨）

この構成により、カタログに複数のバケットを関連付けることができ、バケット名とは別にカタログに名前を付けることができます。

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

    [レイクハウス] に移動

  2. [カタログを作成] をクリックし、[Lakehouse ランタイム カタログ] を選択します。

  3. [カタログタイプ] で [Iceberg Rest Catalog] を選択します。

  4. [Lakehouse カタログ バケットのオプション] で、[複数のバケット カタログ] を選択します。

  5. [カタログのデフォルトの Cloud Storage パス] に、カタログで使用する Cloud Storage パスを入力するか、参照します。

  6. [カタログ ID] に、カタログのカスタム名を入力します。

  7. [メインのロケーション] で、ロケーションを選択します。ロケーションは、メインバケットのリージョンの近くにある必要があります。

  8. [続行] をクリックします。

  9. [データパス] ステップで、Cloud Storage パスを追加する場合は、[パスを追加] をクリックしてパスを入力するか、パスを参照します。

  10. [続行] をクリックします。

  11. [認証方法] で、[エンドユーザー認証情報] または [認証情報ベンディング モード] を選択します。

  12. [作成] をクリックします。

    カタログが作成され、[カタログの詳細] ページが開きます。

  13. [認証情報ベンディング モード] を選択した場合は、次の追加の手順を行います。

    1. [認証方法] で、[バケットの権限を設定]（カタログで複数のバケットを使用している場合は [バケットの権限を設定]）をクリックします。
    2. ダイアログで [確認] をクリックします。

単一バケット カタログを作成する

  1. [Lakehouse] ページで [カタログを作成] をクリックし、[Lakehouse ランタイム カタログ] を選択します。
  2. [カタログタイプ] で、[Iceberg Rest Catalog] または [Hive Metastore] を選択します。
  3. [Iceberg REST カタログ] を選択した場合は、[Lakehouse カタログ バケットのオプション] で [単一バケット カタログ] を選択します。
  4. [デフォルトのカタログの Cloud Storage バケット]（または Apache Hive カタログ エンドポイントの [デフォルトのカタログの Cloud Storage パス]）に、カタログで使用する Cloud Storage バケットを入力するか、参照します。単一バケット カタログの場合、バケットごとに 1 つのカタログのみを使用できます。カタログ名はバケット名と一致します。
  5. [続行] をクリックします。
  6. [認証方法] で、[エンドユーザー認証情報] または [認証情報ベンディング モード] を選択します。
  7. [作成] をクリックします。
  8. [認証情報ベンディング モード] を選択した場合は、次の追加の手順を行います。
    1. [認証方法] で、[バケットの権限を設定] をクリックします。
    2. ダイアログで [確認] をクリックします。

gcloud

複数バケット カタログを作成する（推奨）

この構成により、カタログに複数のバケットを関連付けることができ、バケット名とは別にカタログに名前を付けることができます。

複数のバケット カタログを作成するには（推奨）、gcloud biglake iceberg catalogs create コマンドを実行します。

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

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

  • CATALOG_NAME: カタログの名前。マルチバケット カタログ（推奨）の場合、これはカスタム カタログ名です。
  • PROJECT_ID: 実際の Google Cloudプロジェクト ID。
  • DEFAULT_LOCATION: カタログのデフォルトのストレージ ロケーション。バケット（gs://my-bucket）またはサブパス（gs://my-bucket/path）を指定できます。カタログ内のすべての名前空間とテーブルは、指定されたパスに存在する必要があります。たとえば、gs://my-bucket/path を指定すると、gs://my-bucket/another/path に名前空間やテーブルを作成できません。

  • CREDENTIAL_MODE: 認証方法。エンドユーザー認証情報には end-user を使用し、認証情報ベンディング モードには vended-credentials を使用します。

    注: 認証情報ベンディング モードを使用する場合は、関連付けられているすべてのストレージ バケットに対する Storage オブジェクト ユーザー ロール（roles/storage.objectUser）を、カタログの自動プロビジョニングされた Lakehouse ランタイム カタログ サービス アカウントに明示的に付与する必要があります。

  • RESTRICTED_LOCATIONS: 省略可。追加で許可するストレージ ロケーションのカンマ区切りリスト（gs://my-bucket-1/...,gs://my-bucket-2/... 形式）。パス（gs://my-bucket/path など）を指定する場合、そのバケット内の名前空間またはテーブルはそのパスの下に存在する必要があります。デフォルトのロケーションと制限付きロケーションに構成されたすべての Cloud Storage ロケーションは、同じ地理的リージョン グループまたは管轄区域（米国、ヨーロッパ、カナダ、アジアなど）に存在する必要があります。たとえば、米国のバケットとヨーロッパのバケットを混在させることはできません。サポートされているロケーションの一覧については、レイクハウスのロケーションをご覧ください。

    警告: 認証情報の不正な公開を防ぐため、他のカタログと重複するパスを構成しないでください。詳細については、複数のバケットにまたがるストレージをご覧ください。

  • LOCATION: 省略可。BigQuery との相互運用性を確保するためのカタログのプライマリ リージョン。米国リージョン（US や us-central1 など）または EU リージョン（EU や europe-west4 など）の Cloud Storage バケットの場合は、それぞれ US または EU を指定して、対応する BigQuery マルチリージョンからカタログにアクセスしてクエリを実行できるようにします。詳細については、バケットとカタログのリージョンをご覧ください。

単一バケット カタログを作成する

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

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

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

  • CATALOG_NAME: カタログの名前。単一バケットのカタログの場合、これはカタログで使用される Cloud Storage バケット ID と一致します。
  • PROJECT_ID: 実際の Google Cloudプロジェクト ID。
  • CREDENTIAL_MODE: 認証方法。エンドユーザー認証情報には end-user を使用し、認証情報ベンディング モードには vended-credentials を使用します。

REST

Iceberg REST カタログを作成する

REST API を使用してカタログ管理エンドポイントを作成するには、CreateIcebergCatalog エンドポイントに POST リクエストを送信します。

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=CATALOG_ID

リクエストの本文には、基盤となる Cloud Storage バケット ウェアハウスや認証モードなど、カタログ構成を定義する IcebergCatalog JSON ペイロードを含める必要があります。

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

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • CATALOG_ID: Lakehouse ランタイム カタログの ID。