自 2026 年 4 月 20 日起，BigLake 现已更名为 Lakehouse。BigLake metastore 现已更名为 Lakehouse 运行时目录。Lakehouse API、客户端库、CLI 命令和 IAM 名称保持不变，仍引用 BigLake。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

查询远程数据

在无边界 Lakehouse 中，跨云连接可让您访问外部平台中的远程数据，而无需在云环境之间移动文件。然后，您可以通过 BigQuery、Managed Service for Apache Spark 或开源 Apache Spark 查询联合表。

除了分析查询之外，您还可以使用联合数据来获取 AI 驱动的分析洞见和进行治理：

对话式分析：构建基于数据源（包括联合表）的专用智能体，通过单次对话即可分析跨云数据。
Knowledge Catalog：在联合数据源中分析数据并生成数据洞见。

如需进行更深入的分析，您可以编写使用项目、数据集、表、视图、图表和用户定义的函数的对话式分析代理。这些智能体可跨 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 Data Viewer (roles/bigquery.dataViewer)
运行 BigQuery 作业：BigQuery Job User (roles/bigquery.jobUser)
发现和读取 Lakehouse 目录中的表元数据：BigLake Viewer (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`	自定义身份验证管理器类。对于 OAuth 流程身份验证，请设置为 `org.apache.iceberg.gcp.auth.GoogleAuthManager`。
`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 Storage	`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)：直接从远程云提供方对象存储区读取的总字节数。

如需详细了解缓存概念和数据驻留注意事项，请参阅智能缓存。

后续步骤

受支持的区域和功能。