Apache Iceberg REST カタログ エンドポイントについて

ボーダーレス Lakehouse は、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 Catalog API を実装しています。クライアント クエリエンジンは、標準の REST カタログ API を使用してカタログを操作します。詳細については、Lakehouse が Apache Iceberg REST Catalog API を実装する方法をご覧ください。

リソース階層

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

リソース 説明
カタログ 最上位のコンテナであるカタログを使用すると、名前空間とテーブルを異なるカタログに分割して、論理グループに整理できます。各カタログは、基盤となるメタデータとデータファイルを保存する指定されたウェアハウス ストレージ ロケーション（1 つ以上の Cloud Storage バケットなど）によってバックアップされます。
名前空間 カタログ内のテーブルを整理するために使用される論理グループ。データベース、スキーマ、ディレクトリのように機能します。
テーブル テーブルには、クエリ可能な行と列の定義が含まれています。

カタログと保存場所

カタログの構成によって、カタログの動作と Google Cloud サービスとの統合方法が決まります。複数バケット カタログ（推奨）または単一バケット カタログを構成できます。

どちらのオプションも認証情報の自動販売をサポートしています。

Apache Iceberg REST カタログ エンドポイントに接続するようにクライアント クエリエンジン（Spark や Trino など）を構成する場合は、カタログタイプに基づいてウェアハウス パスを指定します。

  • 複数バケット カタログ: ウェアハウスのパスを bl://projects/PROJECT_ID/catalogs/CATALOG_ID に設定します。
  • 単一バケット カタログ: ウェアハウスパスを gs://CLOUD_STORAGE_BUCKET_NAME に設定します。

複数バケット カタログ（推奨）

この方法では、バケット名とは別にカタログに名前を付けることができます。また、1 つのカタログに複数のバケットを構成できます。基盤となる API では、これは CATALOG_TYPE_BIGLAKE 構成に対応します。

考慮事項:

  • クライアント ウェアハウスの構成（bl://）: 複数バケット カタログに接続するように Iceberg クライアントを構成する場合は、bl:// URI 形式（bl://projects/PROJECT_ID/catalogs/CATALOG_ID）を使用してウェアハウス パスを指定します。bl:// 形式は、クライアント構成時にカタログを識別するためにのみ使用されます。Google Cloud でカタログ自体を作成または構成する場合、ストレージ ロケーション（default_location と restricted_locations）は常に Cloud Storage パス（gs://）として指定されます。
  • 最大ストレージ ロケーション: default_location に加えて、カタログごとに最大 128 個の Cloud Storage バケットまたは restricted_locations のサブパスを指定できます。
  • デフォルトの場所: バケットへのパス（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}）。詳細については、テーブル管理とセキュリティ ルールをご覧ください。

単一バケット カタログ

これは、カタログが指定した単一の Cloud Storage バケット（gs://）で Apache Iceberg メタデータとデータファイルを直接管理する、以前のアプローチです。基盤となる API では、これは CATALOG_TYPE_GCS_BUCKET 構成に対応します。

単一バケットのカタログの場合、カタログ名はバケットの名前に設定されます。

たとえば、バケットに iceberg-bucket という名前を付けると、カタログとバケットの両方でその名前が共有されます。BigQuery で P.C.N.T 構文（my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table など）を使用してカタログをクエリする場合は、この名前を使用します。

考慮事項:

  • 以前のカタログタイプの制限。新しいプロジェクトで以前の単一バケット構成を使用することは、強くおすすめしません。この構成には、いくつかの重要な制限があります。

    • カタログ名: 基盤となる Cloud Storage バケット名にロックされます。
    • プロジェクト: バケットのプロジェクトにロックされます（プロジェクト間のカタログはサポートされていません）。
    • リージョン: バケットのロケーションから厳密に派生し、カスタマイズできません。
    • ストレージ: カタログを単一のバケットに制限します（制限されたロケーションはありません）。

  • クライアント ウェアハウスの構成（gs://）: 単一バケット カタログの Iceberg クライアントを構成する場合は、ウェアハウスのロケーションとして Cloud Storage バケットパス（gs://CLOUD_STORAGE_BUCKET_NAME）を指定します。

  • バケットごとに 1 つのカタログの制限: このレガシー カタログタイプでは、バケットごとに 1 つのカタログのみを使用できます。カタログ名はバケット名と一致する必要があります。

  • マルチバケット カタログにアップグレードする（推奨）: 既存のシングルバケット カタログをマルチバケット カタログにアップグレードできます（推奨）。アップグレードされたカタログには、元のバケットの名前が保持されます。その後、複数のバケットをカタログに関連付けて、制限付きのロケーションを構成できます。

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

Lakehouse ランタイム カタログのカタログ エンドポイントのリージョンは、基盤となる Cloud Storage バケットのリージョンによって決まります。

  • 複数バケット カタログ（推奨）: カタログ リージョンは、default_location で構成されたバケットから派生します。
  • 単一バケット カタログ: カタログ リージョンは、カタログに関連付けられたバケットから厳密に派生し、カスタマイズできません。

マッピングされるカタログ リージョンは、バケットのリージョン タイプによって異なります。

  • 単一リージョン: カタログのリージョンがバケットのリージョンと完全に一致します。
  • デュアルリージョン: カタログ リージョンがバケットのデュアルリージョン（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 を呼び出すことでフェイルオーバーを動的に実行できます。詳細については、カタログを作成するをご覧ください。

データ所在地と主権の要件を満たすために、リクエストを特定のリージョンに直接転送するには、リージョン エンドポイント（biglake.LOCATION.rep.googleapis.com）を使用します。詳細については、Lakehouse のリージョン エンドポイントをご覧ください。

BigQuery からカタログをクエリする

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

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

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

次のステップ