使用目錄聯盟查詢 BigQuery

Lakehouse for Apache Iceberg 透過 BigQuery 目錄聯盟功能，與 BigQuery 互通。這項功能可讓您將 BigQuery 管理的資料表 (例如 Iceberg 管理的資料表) 匯出至外部開放原始碼 (OSS) 引擎，例如 Apache Spark 和 Trino。

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

BigQuery 目錄聯合的運作方式

透過 BigQuery 目錄同盟，您可以透過 Lakehouse 執行階段目錄 Apache Iceberg REST 目錄端點，公開 BigQuery 資料表，例如 Iceberg 受管理資料表和 BigQuery metastore 資料表。

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 執行階段目錄則會做為 Proxy 閘道。當 Lakehouse 執行階段目錄使用 Apache Iceberg REST 目錄端點時，資料表會直接儲存在目錄中，做為 Lakehouse for Apache Iceberg REST 資源。
• 存取控管：聯合資料表使用 BigQuery IAM 權限和存取控制清單 (ACL)。如果 Lakehouse 執行階段目錄使用 Apache Iceberg REST 目錄端點，資料表會使用 Lakehouse for Apache Iceberg ACL。
• 引擎讀寫功能：同盟資料表透過 BigQuery 提供讀寫存取權，但僅允許 Spark 等外部引擎讀取。如果 Lakehouse 執行階段目錄使用 Apache Iceberg REST 目錄端點，資料表會支援 BigQuery API 和外部引擎 (如 Spark) 的讀寫作業。

事前準備

• 系統僅支援 Apache Iceberg V2 (正式發布版) 和 V3 (公開預先發布版) 資料表。不支援 Iceberg V1 資料表。如要升級現有的 V1 資料表，請參閱「將 Iceberg V1 資料表升級至 V2」。

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

2. 啟用 BigLake API。

   啟用 API 時所需的角色

   如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

   啟用 API

必要的角色

如要取得在 BigQuery 中使用目錄聯盟所需的權限，請要求管理員授予您下列 IAM 角色：

• 讀取目錄資源及查詢資料表資料：
  • 專案的「BigLake Viewer」(BigLake 檢視者) (roles/biglake.viewer)
  • Cloud Storage 值區的「Storage 物件檢視者」 (roles/storage.objectViewer)
• 透過 BigQuery 目錄同盟執行資料操縱語言 (DML) 作業：
  • 專案的「BigQuery 資料編輯者」 (roles/bigquery.dataEditor)
  • Cloud Storage 值區的Storage 管理員 (roles/storage.admin)。如果您使用 Managed Service for Apache Spark 等查詢引擎執行 DML 作業，請將這些角色授予您在該引擎中執行工作時使用的服務帳戶。

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

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

設定 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 SQL 直接查詢 (不需要四部分 P.C.N.T 名稱)：

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

更改下列內容：

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

後續步驟

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