Apache Iceberg REST カタログ エンドポイントのコンセプト

Lakehouse ランタイム カタログは、Google Cloud Lakehouse のメタデータを一元管理します。このドキュメントでは、Lakehouse ランタイム カタログのコアコンセプトについて説明します。特に、Apache Iceberg REST カタログ エンドポイントのエンドポイント、そのリソース階層、その他のサポートされているカタログタイプについて説明します。

リソース階層

Apache Iceberg REST カタログ エンドポイントは、リソースの階層を使用してデータを整理します。次の表に、これらのリソースの概要を示します。

リソース 説明
カタログ 最上位のコンテナであるカタログを使用すると、名前空間と テーブルを論理グループに整理できます。そのためには、名前空間とテーブルを異なる カタログに分割します。
名前空間 カタログ内のテーブルを整理するために使用される論理グループ。データベース、スキーマ、ディレクトリのように機能します。
テーブル テーブルには、クエリ可能な行と列の定義が含まれています。

サポートされているカタログタイプ

クライアントを構成するときに、ウェアハウスのロケーションを指定します。この選択 により、カタログの動作と他の Google Cloud サービスとの統合方法が決まります。次の表に、サポートされているカタログタイプを示します。

カタログタイプ 説明
Cloud Storage バケット カタログ内のすべてのデータは単一の Cloud Storage バケットに保存されます。 複数のバケットで共有されるデータには、複数のカタログが必要です。

ウェアハウスの詳細

推奨

  • Cloud Storage バケット ウェアハウス（gs://）: これは標準的なアプローチです。カタログは、指定した Cloud Storage バケット内の Apache Iceberg メタデータとデータファイルを直接管理します。このオプションを使用すると、データ レイアウトを直接制御でき、細かいアクセス制御のための認証情報の提供をサポートできます。 これにより、 Lakehouse Iceberg REST カタログ テーブルを作成して管理できます。

    たとえば、カタログを保存するバケットを作成して iceberg-bucket という名前を付けた場合、カタログ名とバケット名はどちらも iceberg-bucket になります。これは、P.C.N.T 構文を使用して BigQuery でカタログをクエリするときに使用されます。例: my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table

代替サービス

  • BigQuery カタログ フェデレーション（bq://）: このアプローチでは、Apache Iceberg REST カタログ エンドポイントを使用して、BigQuery に表示されるテーブルを管理およびクエリできます。カタログ リソースを作成する必要はありません。詳細については、BigQuery とのカタログ フェデレーションをご覧ください。

バケットとカタログのリージョン

Lakehouse ランタイム カタログの Cloud Storage バケット ウェアハウスの場合、システムは基盤となるバケットのリージョンに合わせてカタログ リージョンを選択します。

  • 単一リージョン バケット: カタログ リージョンはバケット リージョンと 完全に一致します。

  • デュアルリージョン バケット: 事前定義されたデュアルリージョンとユーザー定義のデュアルリージョン（ASIA1、NAM4 など）が含まれます。カタログ リージョンはデュアルリージョンと一致します。

  • マルチリージョン バケット: システムは、マルチリージョンの地理的ドメイン内の カタログのリージョン ロケーションを選択します。デフォルトでは、これらのロケーションは US や EU などの一般的な BigQuery ロケーションと一致しない場合があります。代わりに、地理的ドメイン内のリージョン ロケーション（US マルチリージョン バケットの場合は us-central1 と us-east4 など）になります。

BigQuery は、これらのカタログ内のテーブルに対してクエリを実行すると、カタログのプライマリ リージョン内のリージョンにクエリを転送します。特定の仮想リージョン（US や EU など）でクエリを実行し、そのロケーションにカタログ メタデータが存在しない場合、クエリが失敗する可能性があります。

米国と EU のマルチリージョンのプライマリ リージョンを指定する

US または EU マルチリージョン バケットを使用するカタログの場合、カタログを作成するときにプライマリ リージョンを指定して、BigQuery が対応するリージョンからアクセスできるようにします。

  • Cloud Storage EU マルチリージョン: EU または europe-west4 を指定します。
  • Cloud Storage US マルチリージョン: US または us-central1 を指定します。

システムは、カタログの作成時にプライマリ レプリカを選択しますが、FailoverCatalog を呼び出して動的に更新できます。プライマリ ロケーションの定義の詳細については、Apache Iceberg REST カタログ エンドポイントを使用するをご覧ください。

カタログのクエリ

BigQuery から Lakehouse ランタイム カタログ テーブルをクエリする場合は、 4 つの部分からなる命名構造を使用します。これは通常、P.C.N.T と呼ばれます。

  • Project: カタログを所有する Google Cloud プロジェクト ID。
  • Catalog: Lakehouse ランタイム カタログ カタログの名前。
  • Namespace: Apache Iceberg 名前空間（ BigQuery データセットと同等）。
  • Table: テーブルの名前。

例: my-project.lakehouse-catalog-id.my-namespace.my-table

BigQuery とのカタログ フェデレーション

Apache Iceberg REST カタログ エンドポイント インターフェースを使用して、BigQuery に表示されるテーブルを管理およびクエリできます。

BigQuery カタログ フェデレーション カタログでは、カタログ リソースを作成する必要はありません。BigQuery API が有効になっている任意のプロジェクトで使用できます。これにより、次のことが可能になります。

これらのリソースは BigQuery によって管理されるため、 該当する 必要な権限が必要です。 フェデレーション カタログでは、認証情報の提供はサポートされていません。

フェデレーションを有効にするには、 Apache Iceberg REST カタログ エンドポイントを使用するのクライアント構成例の WAREHOUSE_PATH フィールドで、 bq://projects/PROJECT_ID ウェアハウス形式を使用してクライアントを構成します。また、BigQuery ロケーションを含めて 今後のリクエストを単一のロケーションに制限することもできます。 bq://projects/PROJECT_ID/locations/LOCATION 形式を使用します。

次のステップ