自 2026 年 4 月 20 日起，BigLake 已改名為 Lakehouse。BigLake Metastore 現在稱為 Lakehouse 執行階段目錄。湖倉 API、用戶端程式庫、CLI 指令和 IAM 名稱維持不變，仍會參照 BigLake。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

查詢遠端資料

在無邊界湖倉中，跨雲端連線可讓您存取外部平台的遠端資料，不必在雲端環境之間移動檔案。接著，您就能透過 BigQuery、Managed Service for Apache Spark 或開放原始碼 Apache Spark 查詢聯合資料表。

除了分析查詢，您也可以將聯合資料用於 AI 導向的洞察和管理：

對話式數據分析：建構專門的代理，並以資料來源 (包括聯合資料表) 為基礎，透過單一對話分析不同雲端環境中的資料。
Knowledge Catalog：剖析資料，並從聯合資料來源生成洞察。

如要深入分析，您可以編寫對話式數據分析代理，使用專案、資料集、資料表、檢視表、圖表和 user-defined function。這些代理適用於 BigQuery 標準資料表、Lakehouse 管理的 Apache Iceberg 資料表，以及 Databricks Unity Catalog、AWS Glue、SAP BDC 和 Salesforce 等 Lakehouse 來源。

事前準備

您必須先完成下列事項，才能查詢資料：

確認遠端目錄中有資料。
為 AWS Glue、Databricks Unity Catalog、Snowflake Horizon Catalog、Workday Data Lake 或 SAP Business Data Cloud 設定跨雲端連線。

必要的角色

如要取得查詢聯合資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

在 BigQuery 中查詢資料：BigQuery 資料檢視者 (roles/bigquery.dataViewer)
執行 BigQuery 工作：BigQuery 工作使用者 (roles/bigquery.jobUser)
探索及讀取 Lakehouse 目錄中的資料表中繼資料：BigLake 檢視者 (roles/biglake.viewer)

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

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

查詢資料

設定聯合查詢後，您可以在 BigQuery 中使用標準 SQL，或在 Managed Service for Apache Spark 中使用 Apache Spark，查詢遠端資料。

Lakehouse 會處理中繼資料轉譯和安全資料存取，讓您能像處理 Google Cloud 環境中的本機資料表一樣，處理遠端 Apache Iceberg 資料表。

從 BigQuery 查詢

如要查詢聯合 Apache Iceberg 資料表，請使用標準 BigQuery SQL。資料表路徑採用 4 部分結構：project.federated_catalog.namespace.table。系統會自動處理快取、憑證販售和 CCI 遞移路由。

SELECT
  user_id,
  action,
  COUNT(*) as total_actions
FROM `PROJECT_ID.FEDERATED_CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME`
WHERE event_date >= '2026-04-01'
GROUP BY 1, 2;

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
FEDERATED_CATALOG_NAME：聯合目錄的名稱。
NAMESPACE_NAME：目錄中的命名空間。
TABLE_NAME：資料表名稱。
REGION： Google Cloud 區域。例如：us-east4。

您也可以使用 bq 指令列工具執行查詢：

bq --location="REGION" --project_id="PROJECT_ID" query --use_legacy_sql=false \
  "SELECT * FROM \`PROJECT_ID.FEDERATED_CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME\` LIMIT 10"

透過 Managed Service for Apache Spark 執行查詢

使用 X-Iceberg-Access-Delegation=vended-credentials，將 PySpark 批次工作負載提交至已啟用憑證販售的 Managed Service for Apache Spark。Spark 會使用短期、限定範圍的供應憑證，安全地連線至 S3，完全不需要管理個別的 AWS 憑證或 S3 連接器。

啟用 Managed Service for Apache Spark 的傳出連線。

Managed Service for Apache Spark 無法使用預設網路設定連線至 AWS S3。您必須佈建 Cloud Router 和 Cloud NAT。
```
gcloud compute routers create lakehouse-router \
  --network=NETWORK_NAME \
  --region=REGION

gcloud compute routers nats create lakehouse-nat \
  --router=lakehouse-router \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges \
  --region=REGION
```
更改下列內容：
- NETWORK_NAME：Managed Service for Apache Spark 批次工作負載的網路 (例如 default)。
- REGION：Managed Service for Apache Spark 批次工作負載的區域。

建立 PySpark 應用程式檔案並執行 PySpark 工作。

from pyspark.sql import SparkSession
spark = SparkSession.builder.appName("CATALOG_NAME").getOrCreate()

df = spark.table("CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME")
df.show(10, truncate=False)

將這個檔案上傳至 Cloud Storage，網址為 PYSPARK_FILE。

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=IO_IMPL,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

更改下列內容：

NAMESPACE_NAME：聯合目錄中的命名空間。
TABLE_NAME：聯合目錄中的資料表名稱。
CATALOG_NAME：本機 Spark 目錄的名稱 (例如 my_catalog)。
PYSPARK_FILE：PySpark 應用程式檔案的 gs:// Cloud Storage 路徑。
REGION：Managed Service for Apache Spark 批次工作負載的區域。
RUNTIME_VERSION：Managed Service for Apache Spark 執行階段版本，例如 2.3。
PROJECT_ID：使用 Apache Iceberg REST 目錄端點時，會向這個專案計費。
FEDERATED_CATALOG_NAME：聯合目錄的名稱。
IO_IMPL：與基礎儲存空間相符的 FileIO 實作。

Spark 設定參數

下表列出所有連線所需的常見參數：

參數	說明
`spark.sql.defaultCatalog`	預設目錄名稱 (例如 `CATALOG_NAME`)。
`spark.sql.catalog.CATALOG_NAME`	目錄實作類別。設為 `org.apache.iceberg.spark.SparkCatalog`。
`spark.sql.catalog.CATALOG_NAME.type`	目錄後端類型。如果是 Iceberg REST 目錄，請設為 `rest`。
`spark.sql.catalog.CATALOG_NAME.uri`	REST 目錄端點的 URI。設為 `https://biglake.googleapis.com/iceberg/v1/restcatalog`。
`spark.sql.catalog.CATALOG_NAME.warehouse`	聯合目錄的倉儲位置路徑。設為 `bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME`。
`spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project`	用於帳單和配額歸屬的 Google Cloud 專案 ID。設為 `PROJECT_ID`。
`spark.sql.extensions`	Iceberg SQL 語法和功能的 Spark 工作階段擴充功能。設為 `org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions`。

下表列出驗證參數：

參數	說明
`spark.sql.catalog.CATALOG_NAME.rest.auth.type`	自訂驗證管理工具類別。設為 `org.apache.iceberg.gcp.auth.GoogleAuthManager`，用於 OAuth 流程驗證。
`spark.sql.catalog.CATALOG_NAME.oauth2-server-uri`	OAuth2 權杖伺服器端點 URI。如要使用個人存取權杖 (PAT) 驗證，請設為 `https://oauth2.googleapis.com/token`。
`spark.sql.catalog.CATALOG_NAME.token`	不記名權杖或個人存取權杖 (PAT)。如要進行 PAT 驗證，通常會設為 `$(gcloud auth application-default print-access-token)`。

下表列出儲存空間供應商 (IO_IMPL) 的專屬參數：

儲存空間	`spark.sql.catalog.CATALOG_NAME.io-impl`	附註
Amazon S3	`org.apache.iceberg.aws.s3.S3FileIO`	如果啟用，則需要憑證販售 (`X-Iceberg-Access-Delegation=vended-credentials`)。額外參數：`spark.sql.catalog.CATALOG_NAME.s3.region` (如需區域清單，請參閱 Amazon S3 端點和配額)。
Cloud Storage	`org.apache.iceberg.gcp.gcs.GCSFileIO`	其他參數：`spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint`=`https://oauth2.googleapis.com/token`。
Azure Blob 儲存體	`org.apache.iceberg.azure.adlsv2.ADLSFileIO`	不需要其他儲存空間參數。

如果是 Snowflake，查詢 STRING 資料欄時可能會遇到問題，因為系統會自動最佳化儲存空間。您可以透過下列兩種方式解決這個問題：

方法 1：停用 Spark 的向量化功能：將下列 Spark 設定屬性新增至 --properties 旗標：
spark.sql.iceberg.vectorization.enabled=false
spark.sql.catalog.CATALOG_NAME.table-override.read.parquet.vectorization.enabled=false
方法 2：變更 Snowflake 的序列化政策：將 Snowflake 資料表的儲存空間序列化政策變更為 COMPATIBLE。

監控快取用量和輸出費用節省量

所有跨雲端查詢都會自動啟用 Lakehouse 快取功能。執行查詢時，Lakehouse 會自動將資料區塊快取至 Google Cloud 儲存空間。後續針對相同資料區塊的查詢，會直接從本機快取讀取，而非從遠端雲端重新擷取資料。

如要驗證快取命中率並評估省下的輸出費用，請在 BigQuery 控制台中檢查工作詳細資料，或使用 BigQuery API 或 bq CLI 擷取查詢工作統計資料 (JobStatistics2)：

bq show --format=prettyjson --job=true JOB_ID

在 statistics.query.objectStorageStats (或 Proto API 中的 object_storage_stats) 下方的 JSON 輸出中，工作統計資料會傳回一份清單，其中包含執行期間存取的每個雲端服務供應商項目。每個項目都包含下列欄位：

cloudProvider (cloud_provider)：託管物件儲存庫的遠端雲端服務供應商 (例如 AWS 或 AZURE)。
cacheBytesRead (cache_bytes_read)：從本機 Google Cloud 快取讀取的總位元組數，避免讀取遠端物件儲存庫。
objectStorageBytesRead (object_storage_bytes_read)：直接從遠端雲端服務供應商物件儲存庫讀取的總位元組數。

如要進一步瞭解快取概念和資料落地注意事項，請參閱「智慧型快取」。

後續步驟

支援的地區和功能。