カタログ連携を使用して BigQuery をクエリする

Apache Iceberg 用レイクハウスは、BigQuery カタログ フェデレーションと呼ばれる機能により、BigQuery との相互運用性を提供します。この機能を使用すると、BigQuery で管理されているテーブル（Iceberg マネージド テーブルなど）を、Apache Spark や Trino などの外部オープンソース（OSS）エンジンに公開できます。

メタデータを保存する専用のレイクハウス カタログ コンテナを作成する代わりに、Apache Iceberg REST カタログ エンドポイントは純粋にプロキシ ゲートウェイとして機能します。外部エンジンが bq:// ウェアハウス プレフィックスを使用して接続すると、ゲートウェイはカタログ リクエストを BigQuery の内部カタログに直接転送します。これにより、標準の BigQuery DDL または API を使用して BigQuery 内でテーブルを直接作成して管理できます。また、外部 OSS エンジンには、REST カタログ エンドポイントを介してこれらのテーブルをクエリするための読み取り専用アクセス権が付与されます。

サポートされている表の形式

Apache Iceberg V2 テーブルのみがサポートされています。Iceberg V1 テーブルはサポートされていません。BigQuery カタログに既存の Iceberg V1 テーブルが保存されている場合は、BigQuery カタログ フェデレーションで使用する前に、V2 にアップグレードする必要があります（ALTER TABLE catalog.schema.table SET TBLPROPERTIES ('format-version'='2'); の実行や同様のエンジン オペレーションの使用など）。

BigQuery カタログ フェデレーションの仕組み

BigQuery カタログ フェデレーションを使用すると、Lakehouse ランタイム カタログの Apache Iceberg REST カタログ エンドポイントを介して、Iceberg マネージド テーブルや BigQuery metastore テーブルなどの BigQuery テーブルを公開できます。

BigQuery カタログ連携フローは次のように機能します。

1. BigQuery カタログにテーブルを作成する: DDL ステートメントを使用して、BigQuery に Iceberg マネージド テーブルを作成します。このテーブルは BigQuery カタログに存在し、BigQuery アクセス制御リスト（ACL）に則って管理され、BigQuery REST リソースとして機能します。
2. Lakehouse ランタイム カタログから BigQuery ウェアハウスにフェデレーションする: Lakehouse ランタイム カタログの Apache Iceberg REST API を使用して、bq://projects/PROJECT_ID ウェアハウス パス形式（またはリージョン バージョンの bq://projects/PROJECT_ID/locations/LOCATION）で指定されたウェアハウスにフェデレーションします。これにより、Lakehouse for Apache Iceberg API を介して、Apache Spark などのコンピューティング エンジンから BigQuery テーブルにアクセスできます。この構成では、Spark からは読み取り専用のエクスペリエンスが得られますが、BigQuery からは読み取り / 書き込みのエクスペリエンスが得られます。

Apache Iceberg REST カタログ エンドポイントで管理されるテーブルとの比較

BigQuery カタログ フェデレーションは、Lakehouse ランタイム カタログが Apache Iceberg REST カタログ エンドポイントを使用するワークフローとは次の点で異なります。

• リソース管理とカタログ ストレージ: フェデレーション テーブルは、BigQuery REST リソースとして BigQuery カタログに存在し、Lakehouse ランタイム カタログはプロキシ ゲートウェイとして機能します。レイクハウス ランタイム カタログが Apache Iceberg REST カタログ エンドポイントを使用する場合、テーブルはカタログ内に Apache Iceberg REST リソースの Lakehouse として直接保存されます。
• アクセス制御: 連携テーブルは、BigQuery IAM 権限とアクセス制御リスト（ACL）を使用します。Lakehouse ランタイム カタログが Apache Iceberg REST カタログ エンドポイントを使用する場合、テーブルは Lakehouse for Apache Iceberg ACL を使用します。
• エンジンの読み取りと書き込みの機能: フェデレーション テーブルは、BigQuery を介して読み取り / 書き込みアクセスを提供しますが、Spark などの外部エンジンからは読み取り専用アクセスを提供します。Lakehouse ランタイム カタログで Apache Iceberg REST カタログ エンドポイントを使用する場合、テーブルは BigQuery API と Spark などの外部エンジンの両方からの読み取り / 書き込みオペレーションをサポートします。

始める前に

1. Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

2. BigLake API を有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

   API の有効化

必要なロール

BigQuery でカタログ フェデレーションを使用するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• カタログ リソースの読み取りとテーブルデータのクエリ:
  • プロジェクトに対する BigLake 閲覧者 （roles/biglake.viewer）
  • Cloud Storage バケットに対する Storage オブジェクト閲覧者 （roles/storage.objectViewer）
• BigQuery カタログ連携を使用してデータ操作言語（DML）オペレーションを実行します。
  • プロジェクトに対する BigQuery データ編集者 （roles/bigquery.dataEditor）
  • Cloud Storage バケットに対するストレージ管理者 （roles/storage.admin）。Managed Service for Apache Spark などのクエリエンジンを使用して DML オペレーションを実行する場合は、そのエンジンでジョブを実行するために使用するサービス アカウントにこれらのロールを付与します。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

BigQuery カタログ フェデレーションを設定する

BigQuery カタログ フェデレーションを有効にするには、クライアント アプリケーションを構成するのクライアント構成例の WAREHOUSE_PATH フィールドで、bq://projects/PROJECT_ID ウェアハウス形式を使用してクライアント（Apache Spark や Trino など）を構成します。

bq://projects/PROJECT_ID/locations/LOCATION 形式を使用して BigQuery のロケーションを含め、今後のリクエストを単一のロケーションに制限することもできます。

これらのリソースは BigQuery によって管理されるため、該当する必要な権限が必要です。

連携テーブルの Namespace を作成する

BigQuery カタログ連携用にクライアントを構成したら、連携テーブルの Namespace を作成できます。

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

BigQuery で連携テーブルのクエリを実行する

連携カタログの下に作成したテーブルは BigQuery に表示され、標準の BigQuery SQL を使用して直接クエリできます（4 部構成の P.C.N.T 名は不要です）。

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

次のように置き換えます。

• NAMESPACE_NAME: 名前空間の名前。
• TABLE_NAME: テーブルの名前。

次のステップ

• Google Cloud コンソールでカタログを管理する方法を確認する。
• Lakehouse ランタイム カタログでサポートされている Apache Iceberg テーブルについて学習する。