透過 Apache Iceberg REST 目錄端點查詢 BigQuery 資料表

Lakehouse 透過 Apache Iceberg REST 目錄端點將要求轉送至 BigQuery 目錄，提供與 BigQuery 的互通性。這項功能可讓您將 BigQuery 代管的資料表 (例如 Iceberg 代管資料表) 公開給外部開放原始碼 (OSS) 引擎，例如 Apache Spark 和 Trino。

Apache Iceberg REST 目錄端點純粹做為 Proxy 閘道，而非建立專屬的 Lakehouse 目錄容器來儲存中繼資料。外部引擎使用 bq:// 倉儲前置字串連線時，閘道會將目錄要求直接轉送至 BigQuery 的內部目錄。這樣一來，您就能使用標準 BigQuery DDL 或 API，直接在 BigQuery 中建立及管理資料表，同時讓外部 OSS 引擎透過 REST 目錄端點，以唯讀方式查詢這些資料表。

透過 REST 目錄端點查詢 BigQuery 資料表的運作方式

將要求轉送至 BigQuery 目錄，即可透過 Lakehouse 執行階段目錄 Apache Iceberg REST 目錄端點，公開 BigQuery 資料表，例如 Iceberg 代管資料表和 BigQuery metastore 資料表。

工作流程的運作方式如下：

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) 指定的倉儲。這樣一來，您就能透過 Apache Iceberg REST Catalog API，從 Apache Spark 等 Compute Engine 存取 BigQuery 資料表。在這種設定下，Spark 只能讀取資料，BigQuery 則可讀寫資料。

注意事項

• 將要求轉送至 BigQuery 目錄時，不會建立專屬的 Lakehouse 目錄資源，因此其他目錄層級的概念和設定 (例如資源階層、bucket 和目錄區域，以及四部分 P.C.N.T 命名結構) 不適用於這個方法。在基礎 API 中，這對應於 CATALOG_TYPE_BIGQUERY 設定。將要求轉送至 BigQuery 目錄時，不支援儲存空間存取權委派 (憑證販售)。

• 透過 REST 目錄端點公開 BigQuery 資料表，與存取跨雲端資料不同。雖然這項工作流程會將 Google Cloud 資料表公開給外部 OSS 引擎，但 Lakehouse 會將 Google Cloud 連結至遠端外部目錄 (例如 Databricks Unity Catalog)，以便直接從 BigQuery 和 OSS 引擎查詢儲存在其他雲端服務供應商的資料，而不必遷移資料。如要進一步瞭解該工作流程，請參閱「關於跨雲端資料存取權」。

與 Apache Iceberg REST 目錄端點代管資料表的比較

透過 REST 目錄端點公開 BigQuery 資料表，與 Lakehouse 執行階段目錄使用 Apache Iceberg REST 目錄端點的工作流程，有以下差異：

• 資源管理和目錄儲存空間：BigQuery 目錄中的資料表會以 BigQuery REST 資源的形式儲存在該目錄中，而 Lakehouse 執行階段目錄則做為 Proxy 閘道。當 Lakehouse 執行階段目錄使用 Apache Iceberg REST 目錄端點直接管理資料表時，這些資料表會儲存為 Lakehouse REST 資源。
• 存取控管：BigQuery 目錄中的資料表使用 BigQuery IAM 權限和存取控管清單 (ACL)。直接在 Lakehouse 執行階段目錄中管理的資料表會使用 Lakehouse ACL。
• 引擎讀寫功能：Iceberg 代管資料表可透過 BigQuery 讀取/寫入，並可從 Spark 等外部引擎唯讀存取。透過 Apache Iceberg REST 目錄端點，直接在 Lakehouse 執行階段目錄中管理的資料表，支援 BigQuery 和 Spark 等外部引擎的讀寫作業。

事前準備

1. 確認 Google Cloud 專案已啟用計費功能。

2. 啟用 BigLake API (如果尚未啟用)。

   啟用 API 所需的角色

   您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

必要的角色

如要取得透過 Apache Iceberg REST 目錄端點查詢 BigQuery 資料表所需的權限，請要求管理員授予您下列 IAM 角色：

• 讀取目錄資源及查詢資料表資料：
  • 專案的 BigLake 檢視者 (roles/biglake.viewer)
  • Cloud Storage bucket 的 Storage 物件檢視者 (roles/storage.objectViewer)
• 建立命名空間或修改外部引擎建立的資料表：
  • 專案的 BigQuery 資料編輯者 (roles/bigquery.dataEditor)
  • Cloud Storage bucket 的儲存空間管理員 (roles/storage.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如果您使用 Managed Service for Apache Spark 等外部查詢引擎建立命名空間，或修改外部引擎建立的資料表，請將這些角色授予在該引擎中執行工作的服務帳戶 (Iceberg 代管資料表在外部引擎中為唯讀)。

設定 BigQuery 倉儲的用戶端

如要連線至 BigQuery 倉儲，請在設定用戶端應用程式的用戶端設定範例中，使用 WAREHOUSE_PATH 欄位中的 bq://projects/PROJECT_ID 倉儲格式設定用戶端 (例如 Apache Spark 或 Trino)。

您也可以選擇加入 BigQuery 位置，使用 bq://projects/PROJECT_ID/locations/LOCATION 格式將日後的要求限制在單一位置。

這些資源由 BigQuery 管理，因此您必須具備適用的必要權限。

在 BigQuery 倉儲中建立命名空間

設定用戶端後，即可為資料表建立命名空間。

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 中，並可使用標準 BigQuery SQL 直接查詢 (不需要四部分 P.C.N.T 名稱)：

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

更改下列內容：

• NAMESPACE_NAME：命名空間的名稱。
• TABLE_NAME：資料表名稱。

後續步驟

• 瞭解如何在 Google Cloud 控制台管理目錄。
• 瞭解 Lakehouse 執行階段目錄支援的 Apache Iceberg 資料表。