Lakehouse ランタイム カタログは、Google Cloud Lakehouse のメタデータの一元管理を提供します。このドキュメントでは、Lakehouse ランタイム カタログのコア コンセプトについて説明します。特に、Apache Iceberg REST カタログ エンドポイント、そのリソース階層、その他のサポートされているカタログ タイプについて説明します。
リソース階層
Apache Iceberg REST カタログ エンドポイントは、リソースの階層を使用してデータを整理します。次の表に、これらのリソースの概要を示します。
| リソース | 説明 |
|---|---|
| カタログ | 最上位のコンテナであるカタログを使用すると、Namespace とテーブルを異なるカタログに分割して、論理グループに整理できます。 |
| 名前空間 | カタログ内のテーブルを整理するために使用される論理グループ。データベース、スキーマ、ディレクトリのように機能します。 |
| テーブル | テーブルには、クエリ可能な行と列の定義が含まれています。 |
サポートされているカタログ タイプ
クライアントを構成するときに、ウェアハウスのロケーションを指定します。この選択により、カタログの動作と他のGoogle Cloud サービスとの統合方法が決まります。次の表に、サポートされているカタログ タイプを示します。
| カタログ タイプ | 説明 |
|---|---|
| Cloud Storage バケット | カタログ内のすべてのデータは単一の Cloud Storage バケットに保存されます。複数のバケット間で共有されるデータには、複数のカタログが必要です。 |
| BigQuery カタログ フェデレーション | Apache Iceberg REST カタログ エンドポイントを使用して、BigQuery に表示されるテーブルの管理とクエリを実行できます。詳細については、BigQuery とのカタログ連携をご覧ください。 |
ウェアハウスの詳細
推奨
Cloud Storage バケット ウェアハウス（
gs://）: これは、カタログが指定した Cloud Storage バケット内の Apache Iceberg メタデータとデータファイルを直接管理する標準的なアプローチです。このオプションを使用すると、データ レイアウトを直接制御でき、きめ細かいアクセス制御のための認証情報ベンダーがサポートされます。これにより、Lakehouse Iceberg REST Catalog テーブルを作成して管理できます。たとえば、カタログを保存するためにバケットを作成し、そのバケットに
iceberg-bucketという名前を付けた場合、カタログ名とバケット名の両方がiceberg-bucketになります。これは、後で BigQuery でカタログをクエリするときに P.C.N.T 構文を使用して使用されます。例: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 がこれらのカタログのテーブルに対してクエリを実行すると、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 外部テーブルを作成して管理します。
- Apache Iceberg REST カタログ エンドポイントを使用して、Lakehouse Iceberg REST カタログ テーブルに対してクエリを実行します。
これらのリソースは BigQuery によって管理されるため、該当する必要な権限が必要です。連携カタログでは認証情報のベンディングはサポートされていません。
フェデレーションを有効にするには、Apache Iceberg REST カタログ エンドポイントを使用するのクライアント構成例の WAREHOUSE_PATH フィールドで、bq://projects/PROJECT_ID ウェアハウス形式を使用してクライアントを構成します。bq://projects/PROJECT_ID/locations/LOCATION 形式を使用して BigQuery のロケーションを含め、今後のリクエストを単一のロケーションに制限することもできます。