Lakehouse for Apache Iceberg は、Lakehouse ランタイム カタログを使用してメタデータを管理します。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 カタログ 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の下に名前空間やテーブルをホストすることはできません。ロケーションを指定せずに作成された名前空間には、default_locationが使用されます。 - 制限付きロケーション: 名前空間とテーブルを作成できる追加のバケットまたはパスに、オプションの
restricted_locations構成を指定することもできます。サブパス（gs://my-bucket/pathなど）を指定した場合、その構成を使用して作成されたリソースはそのパスの下に配置する必要があります（たとえば、gs://my-bucket/another/pathは名前空間やテーブルをホストできません）。 - 地理的リージョン グループの要件: バケットは プロジェクト間、リージョン間、構成が異なる（ 単一リージョン、デュアルリージョン、マルチリージョンなど）場合がありますが、デフォルトのロケーションと制限付きロケーションのすべての Cloud Storage ロケーションは、同じ 地理的リージョン グループ（米国、ヨーロッパ、カナダ、アジアなど）に存在する必要があります。たとえば、米国のマルチリージョン バケットをヨーロッパまたはカナダのバケットで構成することはできません。
- バケットあたりの複数のカタログ: 複数のカタログで 同じバケットを参照できます（たとえば、デフォルトのロケーションや 制限付きロケーションが異なる場合）。ただし、この構成はメタデータの競合、誤ったデータの上書き、権限漏洩などのセキュリティ上の問題につながる可能性があるため、強く推奨されません。
- 名前空間: デフォルトまたは制限付きロケーションで構成されたパスの下にある限り、カスタムの名前空間ロケーションを指定できます。これらのカタログで作成されたテーブルには、競合を避けるために、物理パスにランダムな文字列のサフィックスが自動的に追加されます（例:
gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}）。詳細については、テーブルの管理とセキュリティ ルールをご覧ください。
シングル バケット（gs://）
これは、カタログが指定した単一の Cloud Storage バケット内の Apache Iceberg メタデータとデータファイルを直接管理するレガシー アプローチです。基盤となる API では、これは CATALOG_TYPE_GCS_BUCKET
構成に対応します。
Cloud Storage バケット カタログの場合、カタログ名はバケットの名前に設定されます。
たとえば、カタログを保存するバケットを作成して iceberg-bucket という名前を付けた場合、カタログ名とバケット名はどちらも iceberg-bucket になります。これは、P.C.N.T 構文を使用して BigQuery でカタログにクエリを実行するときに使用されます。例: my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table
考慮事項:
レガシー カタログ タイプの制限事項 。新しいプロジェクトでは、レガシーのシングル バケット構成を使用することは強く推奨されません。この構成には、次のような重要な制限があります。
- カタログ名: 基盤となる Cloud Storage バケット名にロックされます。
- プロジェクト: バケットのプロジェクトにロックされます（プロジェクト間のカタログはサポートされていません）。
- リージョン: バケットのロケーションから厳密に派生し、カスタマイズできません。
- ストレージ: カタログを単一のバケットに制限します（制限付きロケーションはありません）。
バケットあたりのカタログ数の制限: このレガシー カタログ タイプでは、バケットごとに 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