Lakehouse for Apache Iceberg は、レイクハウス ランタイム カタログを介してメタデータを管理します。Apache Iceberg REST カタログ エンドポイントを使用すると、システムはデータを厳密なリソース階層に整理します。カタログ構成によって、サポートされているストレージ タイプ、リージョン ルーティングの動作、クエリ フェデレーション オプションが決まります。
機能とコンプライアンス
Lakehouse ランタイム カタログは、標準のテーブル形式をサポートし、オープン API に準拠することで、Iceberg 準拠のクエリ エンジンと統合するように構築されています。
サポートされている表の形式
Apache Iceberg V2 テーブル（一般提供版）と V3 テーブル（プレビュー版）がサポートされています。Iceberg V1 テーブルはサポートされていません。Apache Iceberg REST カタログ エンドポイントで既存の V1 テーブルを使用する前に、サポートされているバージョンにアップグレードする必要があります。詳細については、Iceberg V1 テーブルを V2 にアップグレードするをご覧ください。
API のコンプライアンスと REST オペレーション
Lakehouse ランタイム カタログは、オープン スタンダードの Apache Iceberg REST カタログ API を実装しています。クライアント クエリエンジンは、標準の REST カタログ API を使用してカタログとやり取りします。詳細については、Lakehouse で Apache Iceberg REST Catalog API を実装する方法をご覧ください。
リソース階層
Apache Iceberg REST カタログ エンドポイントは、リソースの階層を使用してデータを整理します。次の表に、これらのリソースの概要を示します。
| リソース | 説明 |
|---|---|
| カタログ | 最上位のコンテナであるカタログを使用すると、名前空間とテーブルを異なるカタログに分割して、論理グループに整理できます。各カタログは、基盤となるメタデータとデータファイルを格納する指定されたウェアハウス ストレージの場所（Cloud Storage バケットや BigQuery 連携プロキシなど）によってバックアップされます。 |
| 名前空間 | カタログ内のテーブルを整理するために使用される論理グループ。データベース、スキーマ、ディレクトリのように機能します。 |
| テーブル | テーブルには、クエリ可能な行と列の定義が含まれています。 |
カタログと保存場所
カタログの構成によって、カタログの動作と Google Cloud サービスとの統合方法が決まります。複数バケット（bl://）カタログ（推奨）または単一バケット（gs://）カタログを構成できます。
どちらのオプションも、きめ細かいアクセス制御のための認証情報ベンダーをサポートしています。
複数バケット（bl://）カタログ（推奨）
この方法では、バケット名とは無関係にカタログに名前を付け、1 つのカタログに複数のバケットを構成できます。基盤となる API では、これは CATALOG_TYPE_BIGLAKE 構成に対応します。
考慮事項:
- デフォルトの場所: デフォルトのストレージ ロケーションとして機能するバケット（
default_location）またはサブパス（gs://my-bucket/pathなど）へのパスを指定します。すべてのカタログ リソース（名前空間とテーブル）は、指定されたパスの下に配置する必要があります。たとえば、gs://my-bucket/pathを指定した場合、gs://my-bucket/another/pathの下に名前空間やテーブルをホストすることはできません。ロケーションを指定せずに作成された Namespace には、default_locationが使用されます。 - 制限付きのロケーション: 名前空間とテーブルを作成できる追加のバケットまたはパスの
restricted_locations構成（省略可）を指定することもできます。サブパス（gs://my-bucket/pathなど）を指定すると、その構成を使用して作成されたリソースは、そのパスの下に配置する必要があります（たとえば、gs://my-bucket/another/pathは Namespace やテーブルをホストできません）。 - 地理的リージョン グループの要件: バケットはプロジェクト間、リージョン間、構成（単一リージョン、デュアルリージョン、マルチリージョンなど）が異なっていても構いませんが、デフォルトの場所と制限付きロケーションのすべての Cloud Storage ロケーションは、同じ地理的リージョン グループ（米国、ヨーロッパ、カナダ、アジアなど）に存在する必要があります。たとえば、ヨーロッパまたはカナダのバケットを使用して米国のマルチリージョン バケットを構成することはできません。
- バケットあたりの複数のカタログ: 複数のカタログで同じバケットを参照できます（たとえば、異なるデフォルトの場所や制限付きの場所を使用する場合など）。ただし、この構成はメタデータの競合、データの誤った上書き、権限漏洩などのセキュリティ上の問題につながる可能性があるため、強く推奨されません。
- 名前空間: デフォルトまたは制限付きの場所に構成されたパスの下にある限り、カスタム名前空間の場所を指定できます。これらのカタログで作成されたテーブルには、競合を回避するために、物理パスにランダムな文字列の接尾辞が自動的に付加されます（例:
gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}）。詳細については、テーブルの管理とセキュリティ ルールをご覧ください。
単一バケット（gs://）カタログ
これは、カタログが指定した単一の Cloud Storage バケット内の Apache Iceberg メタデータとデータファイルを直接管理する従来の方式です。基盤となる API では、これは CATALOG_TYPE_GCS_BUCKET 構成に対応します。
単一バケット カタログの場合、カタログ名はバケットの名前に設定されます。
たとえば、カタログを保存するためにバケットを作成し、そのバケットに iceberg-bucket という名前を付けた場合、カタログ名とバケット名の両方が iceberg-bucket になります。これは、後で BigQuery でカタログをクエリするときに P.C.N.T 構文を使用して使用されます。例: my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table。
考慮事項:
以前のカタログ タイプの制限事項。新しいプロジェクトでは、以前の単一バケット構成を使用することは強く推奨されません。この構成には、次のような重大な制限事項があります。
- カタログ名: 基盤となる Cloud Storage バケット名にロックされます。
- プロジェクト: バケットのプロジェクトにロックされます（プロジェクト間のカタログは対象外です）。
- リージョン: バケットのロケーションから厳密に派生し、カスタマイズできません。
- ストレージ: カタログを単一のバケットに制限します（制限されたロケーションはありません）。
バケットあたりのカタログ 1 つの制限: この以前のカタログタイプでは、バケットごとに 1 つのカタログのみを使用でき、カタログ名はバケット名と一致している必要があります。
複数バケット（
bl://）カタログにアップグレードする（推奨）: 既存の単一バケット（gs://）カタログを複数バケット（bl://）カタログにアップグレードできます（推奨）。アップグレードされたカタログは、元のバケットの名前を保持します。その後、複数のバケットをカタログに関連付けて、制限付きロケーションを構成できます。
バケットとカタログのリージョン
Lakehouse ランタイム カタログ内のカタログ エンドポイントのリージョンは、基盤となる Cloud Storage バケットのリージョンによって決まります。
- 複数バケット（
bl://）カタログ（推奨）: カタログ リージョンは、default_locationで構成されたバケットから派生します。 - 単一バケット（
gs://）: カタログ リージョンは、カタログに関連付けられたバケットから厳密に派生し、カスタマイズできません。
マッピングされたカタログ リージョンは、バケットのリージョン タイプによって異なります。
- 単一リージョン: カタログのリージョンがバケットのリージョンと完全に一致します。
- デュアルリージョン: カタログ リージョンがバケットのデュアルリージョン（
ASIA1やNAM4など）と一致します。 - マルチリージョン: カタログ リージョンは、マルチリージョンの地理的ドメイン内の特定のリージョン ロケーションに設定されます。デフォルトでは、これは
USやEUなどの一般的な BigQuery マルチリージョンと一致しない場合があります（たとえば、USマルチリージョン バケットはus-central1またはus-east4にマッピングされます）。
BigQuery がこれらのカタログ内のテーブルに対してクエリを実行すると、クエリはカタログのプライマリ リージョンに転送されます。特定の仮想リージョン（US や EU など）のテーブルをクエリし、そのロケーションにカタログ メタデータが存在しない場合、クエリは失敗します。
マルチリージョンのプライマリ リージョン
BigQuery が US または EU マルチリージョンからカタログ テーブルをクエリできるようにするには、カタログの作成時に US または EU をプライマリ リージョンとして指定します。
次の構成では、マルチリージョン（US または EU）をプライマリ リージョンとして指定できます。
default_location バケットが次の状態の場合:
USまたはEUマルチリージョン バケット。- これらのマルチリージョン内のシングルリージョン バケット（
us-central1やeurope-west4など）。 - これらのエリア内のデュアルリージョン バケットまたはカスタム デュアルリージョン バケット（
NAM4やEUR4など）。
プライマリ レプリカはカタログの作成時に定義されますが、FailoverCatalog を呼び出すことで動的にフェイルオーバーを実行できます。詳細については、カタログを作成するをご覧ください。
BigQuery からカタログをクエリする
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