Lakehouse for Apache Iceberg 通过 Lakehouse 运行时目录管理元数据。使用 Apache Iceberg REST Catalog 端点时，系统会将数据整理成严格的资源层次结构。目录配置决定了支持的存储类型、区域路由行为和查询联合选项。
功能和合规性
Lakehouse 运行时目录旨在通过支持标准表格式和遵循开放式 API，与符合 Iceberg 标准的查询引擎集成。
支持的表格格式
支持 Apache Iceberg V2 表（正式版）和 V3 表（预览版）。 不支持 Iceberg V1 表。在将现有 V1 表与 Apache Iceberg REST Catalog 端点搭配使用之前，您必须将这些表升级到受支持的版本。如需了解详情，请参阅将 Iceberg V1 表升级到 V2。
API 合规性和 REST 操作
Lakehouse 运行时目录实现了开放标准 Apache Iceberg REST Catalog API。客户端查询引擎使用标准 REST 目录 API 与目录进行交互。如需了解详情，请参阅 Lakehouse 如何实现 Apache Iceberg REST Catalog API。
资源层次结构
Apache Iceberg REST Catalog 端点使用资源层次结构来整理数据。下表简要介绍了这些资源：
| 资源 | 说明 |
|---|---|
| 目录 | 顶级容器，目录可让您通过将命名空间和表拆分为不同的目录，将它们整理为逻辑组。每个目录都由指定的仓库存储位置（例如 Cloud Storage 存储桶或 BigQuery 联合代理）提供支持，用于存储其底层元数据和数据文件。 |
| 命名空间 | 用于整理目录中表的逻辑分组，其功能类似于数据库、架构或目录。 |
| 表 | 表包含可查询的行和列的定义。 |
目录和存储位置
目录的配置决定了其运行方式以及与 Google Cloud 服务的集成方式。您可以配置多存储桶 (bl://) 目录（推荐）或单存储桶 (gs://) 目录。
这两种选项都支持凭据自动售卖，以实现精细的访问权限控制。
多存储桶 (bl://) 目录（推荐）
借助此方法，您可以独立于任何存储桶名称来命名目录，并为单个目录配置多个存储桶。在底层 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：
- 项目：拥有目录的 Google Cloud 项目 ID。
- Catalog：Lakehouse 运行时目录的名称。
- Namespace：Apache Iceberg 命名空间（相当于 BigQuery 数据集）。
- Table：表的名称。
例如 my-project.lakehouse-catalog-id.my-namespace.my-table。