无边界 Lakehouse 通过 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 存储桶）提供支持，这些位置存储了其底层元数据和数据文件。 |
| 命名空间 | 用于整理目录中表的逻辑分组，其功能类似于数据库、架构或目录。 |
| 表 | 表包含可查询的行和列的定义。 |
商品目录和存储位置
目录的配置决定了其运作方式以及与 Google Cloud 服务的集成方式。您可以配置多存储桶目录（推荐）或单存储桶目录。
这两个选项都支持凭据分发。
配置客户端查询引擎（例如 Spark 或 Trino）以连接到 Apache Iceberg REST Catalog 端点时，您需要根据目录类型指定仓库路径：
- 多存储桶目录：将仓库路径设置为
bl://projects/PROJECT_ID/catalogs/CATALOG_ID。 - 单存储桶目录：将仓库路径设置为
gs://CLOUD_STORAGE_BUCKET_NAME。
多存储桶目录（推荐）
通过这种方法，您可以独立于任何存储桶名称来命名目录，并为单个目录配置多个存储桶。在底层 API 中，这对应于 CATALOG_TYPE_BIGLAKE 配置。
注意事项：
- 客户端仓库配置 (
bl://)：配置 Iceberg 客户端以连接到多存储桶目录时，请使用bl://URI 格式指定仓库路径：bl://projects/PROJECT_ID/catalogs/CATALOG_ID。bl://格式仅在客户端配置期间用于标识目录。在 Google Cloud 中创建或配置目录本身时，存储位置（default_location和restricted_locations）始终指定为 Cloud Storage 路径 (gs://)。 - 存储位置数量上限：除了
default_location之外，您还可以为每个目录指定最多 128 个 Cloud Storage 存储桶或restricted_locations中的子路径。 - 默认位置：您提供存储桶 (
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}）。如需了解详情，请参阅表管理和安全规则。
单存储桶目录
这是一种旧方法，其中目录直接管理您指定的单个 Cloud Storage 存储桶 (gs://) 中的 Apache Iceberg 元数据和数据文件。在底层 API 中，这对应于 CATALOG_TYPE_GCS_BUCKET 配置。
对于单存储桶目录，目录名称会设置为存储桶的名称。
例如，如果您将存储桶命名为 iceberg-bucket，则目录和存储桶都会使用该名称。在 BigQuery 中使用 P.C.N.T 语法查询目录时，请使用此名称，例如 my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table。
注意事项：
旧版目录类型限制。对于新项目，强烈建议不要使用旧版单存储桶配置。此配置存在一些严重的限制：
- 目录名称：锁定为底层 Cloud Storage 存储桶名称。
- 项目：锁定到存储桶的项目（不支持跨项目目录）。
- 区域：严格根据存储桶的位置确定，无法自定义。
- 存储：将目录限制为单个存储桶（无受限位置）。
客户端仓库配置 (
gs://)：为单存储桶目录配置 Iceberg 客户端时，请将 Cloud Storage 存储桶路径 (gs://CLOUD_STORAGE_BUCKET_NAME) 指定为仓库位置。每个存储桶一个目录限制：对于此旧版目录类型，每个存储桶只能有一个目录，并且目录名称必须与存储桶名称一致。
升级到多存储桶目录（推荐）：您可以将现有的单存储桶目录升级为多存储桶目录（推荐）。升级后的目录会保留原始存储桶的名称。之后，您可以将多个存储桶与目录相关联，并配置受限位置。
存储桶和目录区域
Lakehouse 运行时目录中目录端点的区域由其底层 Cloud Storage 存储桶的区域决定：
- 多存储桶目录（推荐）：目录区域派生自
default_location中配置的存储桶。 - 单存储桶目录：目录区域严格派生自与目录关联的存储桶，无法自定义。
映射的目录区域因存储桶的区域类型而异：
- 单区域：目录区域与存储桶的区域完全一致。
- 双区域：目录区域与存储桶的双区域（例如
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 动态执行故障切换。如需了解详情，请参阅创建目录。
如需根据数据驻留和主权要求将请求直接路由到特定区域，您可以使用区域端点 (biglake.LOCATION.rep.googleapis.com)。如需了解详情，请参阅 Lakehouse 区域端点。
从 BigQuery 查询目录
从 BigQuery 查询 Lakehouse 运行时目录表时，您需要使用由四个部分组成的命名结构，通常称为 P.C.N.T：
- 项目：拥有目录的 Google Cloud 项目 ID。
- Catalog：Lakehouse 运行时目录的名称。
- Namespace：Apache Iceberg 命名空间（等同于 BigQuery 数据集）。
- 表：表的名称。
例如 my-project.lakehouse-catalog-id.my-namespace.my-table。