通过 Apache Iceberg REST Catalog 端点查询 BigQuery 表

Lakehouse 通过将请求通过 Apache Iceberg REST 目录端点路由到 BigQuery 目录，实现与 BigQuery 的互操作性。借助此功能，您可以向 Apache Spark 和 Trino 等外部开源 (OSS) 引擎公开由 BigQuery 管理的表，例如 Iceberg 托管表。

Apache Iceberg REST 目录端点纯粹充当代理网关，而不是创建专用的 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 目录资源，因此其他目录级概念和配置（例如资源层次结构、存储桶和目录区域以及由四部分组成的 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 运行时目录则充当代理网关。当 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 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

所需的角色

如需获得通过 Apache Iceberg REST 目录端点查询 BigQuery 表所需的权限，请让管理员向您授予以下 IAM 角色：

  • 读取目录资源和查询表数据：
  • 创建命名空间或修改由外部引擎创建的表：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如果您使用 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

如需在 BigQuery 仓库中创建命名空间，请添加 LOCATION 和 DBPROPERTIES 子句：

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;")

替换以下内容：

  • NAMESPACE_NAME：命名空间的名称。
  • BUCKET_NAME：您与目录搭配使用的 Cloud Storage 存储桶。
  • LOCATION：BigQuery 位置。默认值为 US 多区域。

Trino

如需在 BigQuery 仓库中创建架构，请添加 LOCATION 和 gcp-region 属性：

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

替换以下内容：

  • CATALOG_NAME：使用 Apache Iceberg REST 目录端点的 Trino 目录的名称。
  • SCHEMA_NAME：架构的名称。
  • BUCKET_NAME：您与目录搭配使用的 Cloud Storage 存储桶。
  • LOCATION：BigQuery 位置。默认值为 US 多区域。

在 BigQuery 中查询表

您在 BigQuery 仓库中创建的表在 BigQuery 中可见，并且可以使用标准 BigQuery SQL 直接查询（无需四部分 P.C.N.T 名称）：

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

替换以下内容：

  • NAMESPACE_NAME：您的命名空间名称。
  • TABLE_NAME：表的名称。

后续步骤