使用目录联合查询 BigQuery

Lakehouse for Apache Iceberg 通过一项称为 BigQuery 目录联合 的功能提供与 BigQuery 的互操作性。借助此功能，您可以将 BigQuery 管理的表（例如 Iceberg 管理的表）公开给外部开源 (OSS) 引擎，例如 Apache Spark 和 Trino。

Apache Iceberg REST Catalog 端点纯粹充当代理网关，而不是创建专用的 Lakehouse 目录容器来存储元数据。当外部引擎使用 bq:// 仓库前缀进行连接时，网关会将它们的目录请求直接路由到 BigQuery 的内部目录。 这样，您就可以使用标准 BigQuery DDL 或 API 直接在 BigQuery 中创建和管理表，同时让外部 OSS 引擎通过 REST Catalog 端点对这些表进行只读查询。

BigQuery 目录联合的工作原理

借助 BigQuery 目录联合，您可以通过 Lakehouse 运行时目录 Apache Iceberg REST Catalog 端点公开 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 获得读写体验。

BigQuery 目录联合与 Lakehouse 运行时目录使用 Apache Iceberg REST Catalog 端点的工作流不同，具体如下：

• 资源管理和目录存储：联合表作为 BigQuery REST 资源驻留在 BigQuery 目录中，而 Lakehouse 运行时目录充当代理网关。当 Lakehouse 运行时目录使用 Apache Iceberg REST Catalog 端点时，表直接存储在目录中，作为 Lakehouse for Apache Iceberg REST 资源。
• 访问权限控制：联合表使用 BigQuery IAM 权限和访问控制列表 (ACL)。当 Lakehouse 运行时目录使用 Apache Iceberg REST Catalog 端点时，表使用 Lakehouse for Apache Iceberg ACL。
• 引擎读写功能：联合表通过 BigQuery 提供读写 访问权限，但通过 Spark 等外部 引擎提供只读访问权限。当 Lakehouse 运行时目录使用 Apache Iceberg REST Catalog 端点时，表支持来自 BigQuery API 和 Spark 等外部引擎的读写操作。

准备工作

• 仅支持 Apache Iceberg V2（正式版）和 V3（公开预览版）表。不支持 Iceberg V1 表。如需升级现有的 V1 表，请参阅将 Iceberg V1 表升级到 V2。

1. 验证是否已为您的 Google Cloud 项目启用结算功能。

2. 启用 BigLake API。

   启用 API 所需的角色

   如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

   启用 API

所需角色

如需获得在 BigQuery 中使用目录联合所需的权限，请让管理员向您授予以下 IAM 角色：

• 读取目录资源和查询表数据：
  • 项目的 BigLake Viewer (roles/biglake.viewer) 角色
  • Storage Object Viewer (roles/storage.objectViewer) 针对 Cloud Storage 存储桶
• 使用 BigQuery 目录联合执行数据操纵语言 (DML) 操作：
  • 项目的 BigQuery Data Editor (roles/bigquery.dataEditor) 角色
  • 针对 Cloud Storage 存储桶的 Storage Admin (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 表。