Apache Iceberg REST Catalog 端点简介

Lakehouse for Apache Iceberg 通过 Lakehouse 运行时目录 管理元数据。使用 Apache Iceberg REST 目录端点时，系统会将数据整理到严格的资源层次结构中。目录配置决定了支持的存储类型、区域路由行为和查询联合选项。

功能和合规性

Lakehouse 运行时目录旨在与符合 Iceberg 标准的查询引擎集成，方法是支持标准表格式并遵循开放 API。

支持的表格式

支持 Apache Iceberg V2 表（正式版）和 V3 表（预览版）。 不支持 Iceberg V1 表。在使用 Apache Iceberg REST 目录端点处理现有 V1 表之前，您必须将这些表升级到受支持的版本。如需了解详情，请参阅将 Iceberg V1 表升级到 V2。

API 合规性和 REST 操作

Lakehouse 运行时目录实现了开放标准 Apache Iceberg REST Catalog API。客户端查询引擎使用标准 REST 目录 API 与目录进行交互。如需了解详情，请参阅 Lakehouse 如何实现 Apache Iceberg REST Catalog API。

资源层次结构

Apache Iceberg REST 目录端点使用资源层次结构来整理数据。下表简要介绍了这些资源：

目录和存储位置

目录的配置决定了其运行方式以及与 Google Cloud 服务的集成方式。您可以配置多存储桶 (bl://) 目录（推荐）或单存储桶 (gs://) 目录。

这两种选项都支持凭据销售。

多存储桶 (bl://) 目录（推荐）

借助此方法，您可以独立于任何存储桶名称来命名目录，并为单个目录配置多个存储桶。您最多可以为每个目录指定 15 个存储分区。

在底层 API 中，这对应于 CATALOG_TYPE_BIGLAKE 配置，下文将对此进行详细介绍。

注意事项：

• 默认位置：您需要提供存储桶 (default_location) 或子路径（例如 gs://my-bucket/path）的路径，以用作默认存储 位置。所有目录资源（命名空间和表）都必须位于指定的路径下。例如，如果您指定 gs://my-bucket/path，则无法在 gs://my-bucket/another/path 下托管命名空间或表。对于在创建时未指定位置的命名空间，系统会使用 default_location。
• 受限位置：您还可以提供可选的 restricted_locations配置，用于指定可创建 命名空间和表的其他存储分区或路径。如果您指定子路径（例如 gs://my-bucket/path），则使用该配置创建的任何资源都必须位于该路径下（例如，gs://my-bucket/another/path 无法托管命名空间或表）。
• 地理区域组要求：虽然存储分区可以是 跨项目、跨区域的，并且具有不同的配置（例如 单区域、双区域或多区域），但默认位置和受限位置中的所有 Cloud Storage 位置都必须位于同一 地理区域组（例如美国、欧洲、加拿大或亚洲）中。例如，您无法使用欧洲或加拿大的存储桶配置美国多区域存储桶。
• 每个存储桶有多个目录：您可以让多个目录指向 同一存储桶（例如，使用不同的默认位置或 受限位置）。但是，我们强烈建议您不要进行此配置，因为它可能会导致元数据冲突、意外的数据覆盖或权限泄露等安全问题。
• 命名空间：允许指定自定义命名空间位置，只要 这些位置位于默认位置或受限位置中配置的路径下即可。 请注意，在这些目录中创建的表会在其物理路径中自动附加随机字符串 后缀，以防止冲突（例如， gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}）。如需 了解详情，请参阅表管理和安全 规则。

单存储桶 (gs://) 目录

这是旧版方法，目录直接管理您指定的单个 Cloud Storage 存储桶中的 Apache Iceberg 元数据和数据文件。在 底层 API 中，这对应于 CATALOG_TYPE_GCS_BUCKET 配置。

对于单存储桶目录，目录名称设置为存储桶的名称。

例如，如果您创建了一个存储桶来存储目录，并将其命名为 iceberg-bucket，则目录名称和存储桶名称均为 iceberg-bucket。稍后，当您使用 P.C.N.T 语法在 BigQuery 中查询目录时，系统会使用此名称。例如 my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table。

注意事项：

• 旧版目录类型限制 。对于新项目，我们强烈建议您不要使用旧版单存储桶配置。此配置存在一些严重限制：

  • 目录名称：锁定到底层 Cloud Storage 存储桶名称。
  • 项目：锁定到存储桶的项目（不支持跨项目目录）。
  • 区域：严格派生自存储桶的位置，无法自定义。
  • 存储空间：将目录限制为单个存储桶（没有受限位置）。

• 每个存储桶只能有一个目录的限制：对于这种旧版目录类型，您 每个存储桶只能有一个目录，并且目录名称必须与 存储桶名称一致。

• 升级到多存储桶 (bl://) 目录（推荐）：您可以 将现有的单存储桶 (gs://) 目录 升级到多存储桶 (bl://) 目录（推荐）。升级后的目录会保留原始存储桶的名称。之后，您可以将多个存储分区与目录相关联，并配置受限位置。

存储分区和目录区域

Lakehouse 运行时目录中目录端点的区域由其底层 Cloud Storage 存储桶的区域决定：

• 多存储桶 (bl://) 目录：（推荐）：目录区域派生自 default_location中配置的存储桶。
• 单存储桶 (gs://) ：目录区域严格派生自与目录关联的存储桶，无法自定义。

映射的目录区域因存储桶的区域类型而异：

• 单区域：目录区域与存储桶的区域完全一致。
• 双区域：目录区域与存储桶的双区域（例如 或 ASIA1 或 NAM4）一致。
• 多区域：目录区域设置为多区域地理网域内的特定区域位置 。默认情况下，这可能与常见的 BigQuery 多区域（例如 US 和 EU）不一致（例如，US 多区域存储桶映射到 us-central1 或 us-east4）。

当 BigQuery 在这些目录中的表上运行查询时，它会将查询路由到目录的主区域。如果您在特定虚拟区域（例如 US 或 EU）中查询表，并且该位置中不存在目录元数据，则查询会失败。

多区域的主区域

如需允许 BigQuery 从 US 或 EU 多区域查询目录表，请在创建目录时将 US 或 EU 指定为主区域。

您可以在以下配置中将多区域（US 或 EU）指定为主区域：

如果 default_location 存储桶是：

• US 或 EU 多区域存储桶。
• 这些多区域中的单区域存储桶（例如 us-central1 或 europe-west4）。
• 这些区域中的双区域或自定义双区域存储桶（例如 NAM4 或 EUR4）。

主副本是在您创建目录时定义的，但您可以通过调用 FailoverCatalog 动态执行故障切换。如需了解更多 信息，请参阅创建目录。

从 BigQuery 查询目录

从 BigQuery 查询 Lakehouse 运行时目录表时，您需要使用四部分命名结构，通常称为 P.C.N.T：

• Project：拥有目录的 Google Cloud 项目 ID。
• Catalog：Lakehouse 运行时目录的名称。
• Namespace：Apache Iceberg 命名空间（相当于 BigQuery 数据集）。
• Table：表的名称。

例如，my-project.lakehouse-catalog-id.my-namespace.my-table。

后续步骤

• 设置 Apache Iceberg REST 目录端点