配置表格选项

通过配置表选项，您可以选择启用 BigQuery 写入互操作性或表管理（自动存储优化），以便在湖仓一体运行时目录中管理 Apache Iceberg 表。这些选项是基础设置，可扩展表操作的功能。

通过配置特定的表属性，您可以实现与 BigQuery DML 的写入互操作性，或启用自动表管理（存储空间优化）。

在 Lakehouse 运行时目录中使用表时，了解不同的表类型及其选择启用功能会很有帮助。如需详细了解如何使用 Apache Iceberg 表，请参阅 Apache Iceberg 表概览。

准备工作

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

2. 启用 BigLake API。

   启用 API 所需的角色

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

   启用 API

3. 使用 Apache Iceberg REST 目录端点设置 Lakehouse 运行时目录。

所需的角色

如需获得配置表格选项所需的权限，请让管理员向您授予项目和存储桶的以下 IAM 角色：

• 在凭据自动售卖模式下配置表属性：BigLake Editor (roles/biglake.editor) - 项目
• 在非凭证自动售卖模式下配置表属性：
  • BigLake Editor (roles/biglake.editor) - 项目
  • Storage Object User (roles/storage.objectUser) - Cloud Storage 存储桶

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

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

配置注意事项

配置表格选项时，请考虑以下要求和默认行为：

支持的 Iceberg 表

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

凭证分发要求

如需选择启用自动表管理，您的 Lakehouse 运行时目录必须在目录级启用凭据自动售卖。表管理后台作业使用凭据自动售卖服务账号进行身份验证并更新底层存储数据文件。

启用 BigQuery DML

启用 BigQuery 数据操纵语言 (DML) 语句后，即可在通过开源引擎创建的 Apache Iceberg 表上实现 BigQuery 的写入互操作性。

支持的语句包括 INSERT、UPDATE、DELETE 和 MERGE，以及标准 DDL 语句（如 CREATE TABLE、ALTER TABLE 和 DROP TABLE），但 BigQuery 中的 Apache Iceberg 表不支持的语句除外。

为新表启用 BigQuery DML

从 BigQuery 创建表时，系统会默认启用 BigQuery DML 和自动表管理。通过开源引擎创建表时，请使用引擎的 DDL 语法配置 gcp.biglake.bigquery-dml.enabled = true 表属性。

例如，在 Spark SQL 中：

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

为现有表启用 BigQuery DML

如需在现有表上启用 BigQuery DML，请更新表属性。

例如，在 Spark SQL 中：

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

停用 BigQuery DML

停用 BigQuery DML 会使 BigQuery 只能读取相应表，并停止自动表管理。

例如，在 Spark SQL 中：

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

启用表格管理

表管理可自动执行后台进程，以优化存储空间并管理数据和元数据生命周期，例如压缩和垃圾回收。

借助表格管理功能，您可以执行以下操作：

• 快照过期和垃圾回收：快照过期功能可管理表快照中数据和元数据文件的保留和删除。在任何数据突变后，此操作都会在后台自动运行。系统会根据用户配置的 Iceberg 表属性 history.expire.max-snapshot-age-ms 和 history.expire.min-snapshots-to-keep 来使表中的快照过期。它通过创建另一个额外的快照定义来移除过期的快照条目，该快照定义通过不再包含对已移除快照的引用的新元数据文件来体现。

  • 限制：如果表使用标记或分支，则会跳过快照过期和关联的垃圾回收。如需了解详情，请参阅限制。

  • 限制：自动表管理功能不会处理孤立文件的移除。如需了解详情，请参阅限制。

• 合并（压缩）：合并负责通过将小文件合并为大文件来维护数据的形状。在任何数据发生变动后，Coalesce 会在后台自动运行。如果文件的平均未压缩大小小于目标文件大小 256 MB 的 50%，则会选择这些文件进行压缩。每次合并操作都会生成一个新的表格快照。合并作业通常会在任何正在运行的 DML 操作之后让步并重试。不过，为了防止存储空间优化无限期地处于饥饿状态，如果数据符合合并条件，系统会每 24 小时强制触发一次合并作业。

• 监控表管理作业：所有后台表管理作业都会记录在 BigQuery 的 INFORMATION_SCHEMA.JOBS 视图中。您可以查询此视图来跟踪这些操作，就像监控其他 BigQuery 作业一样。如需详细了解如何查询作业信息，请参阅获取 Iceberg 存储优化作业。

  表管理作业的频率与数据变更活动直接相关。频繁的小规模插入或更新会触发更频繁的后台任务。如果没有对表进行写入操作，您可能会发现一段时间内没有后台作业。相反，如果写入量较大，INFORMATION_SCHEMA 中可能会显示更多作业活动。

为新表启用表格管理功能

从 BigQuery 创建表时，系统会默认启用 DML 和自动表管理。通过开源引擎创建表时，请配置 gcp.biglake.table-management.enabled 属性。启用表管理功能会自动启用 BigQuery DML（如果尚未启用）。

例如，在 Spark SQL 中：

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

为现有表启用表管理

如需在现有表上启用表管理，请更新表属性。

例如，在 Spark SQL 中：

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

停用表格管理

停用表管理功能后，系统将不会再将未来的后台优化作业排入队列，但正在进行中的作业会完成。停用表管理不会停用 BigQuery DML。

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

限制

对于受管理的功能（例如 BigQuery 写入互操作性和自动表管理），存在以下限制：

一般限制

• 只有在 Lakehouse 运行时目录中使用 Apache Iceberg REST 目录端点创建的 Apache Iceberg 表才支持托管功能。
• 所有现有的 BigQuery 管理的 Apache Iceberg 表限制均适用于启用托管功能的作业。
• 对于采用 Apache Iceberg 格式版本 3 的表，不支持受管理的功能。只有格式版本 2（Iceberg v2 规范）的表可以选择启用受管理的功能。
• 具有高级分区（例如按 STRING 分区、多列分区或分区演变）的表不支持受管功能。
• 对于配置了排序顺序的表（例如，使用 WRITE ORDER BY 过程或设置 write.distribution.mode = range），不支持受管功能。
• 使用读时合并模式的 Iceberg v2 表不支持受管理的功能。只有使用写入时复制更新、删除和合并模式的表才能选择启用受管理的功能。
• 受管理的功能不支持使用 gzip、lz4 或 brotli 解码器 (write.parquet.compression.codec) 压缩的数据文件。数据文件仅支持 zstd 和 snappy 压缩类型。
• 如果架构包含引用结构中嵌套路径或字段的嵌套主键标识符 (identifier-field-ids)，则表不支持受管理的功能。
• 对于具有自定义数据或元数据位置（write.data.path 和 write.metadata.path）的表，不支持受管功能。需要使用默认 Cloud Storage 存储桶位置来存放数据和元数据文件。
• 由 Lakehouse 运行时目录管理的 Apache Iceberg 表不支持 BigQuery 集群。
• 如果在 BigQuery 中创建的表使用 NUMERIC 数据类型，则来自 Spark 的任何架构更新都会失败，因为 Spark 会将 NUMERIC 读取为 NUMERIC(38,9)。作为一种解决方法，在 BigQuery 中创建具有 NUMERIC 类型的表时，请将精度明确设置为 NUMERIC(38,9)。
• 已知问题：不支持使用 DDL (ALTER TABLE ... DROP COLUMN) 在 BigQuery 中删除列，然后立即重新添加同名列。

时间旅行的限制

• 启用表格管理后，建议 history.expire.max-snapshot-age-ms 属性的最大值为 7 天。
• BigQuery 项目级或数据集级时间旅行配置不适用。仅 Iceberg 表属性和默认值处于有效状态。

表管理方面的限制

• 如果表包含带有标记或分支的快照，则会跳过整个表的快照过期。使用 ALTER... RETAIN x DAYS 设置的自定义保留期限会被忽略，并且为 history.expire.max-ref-age-ms 属性设置的任何值也会被忽略。开源引擎仍可执行快照过期操作。
• 自动表管理不会使架构或分区规范过期。即使没有快照引用这些架构 ID，metadata.json 文件也会保留架构和分区规范的完整历史记录。

• 由 BigQuery 或开源引擎创建的孤立文件不会通过自动表管理功能清理。开源引擎可以执行孤立文件清理（例如，使用 Spark remove_orphan_files 过程，并将 prefix_listing 选项设置为 true）。

• Coalesce 不支持 Z 排序和线性排序。如果您的表格包含这些属性，则无法保证在合并运行后布局保持不变。如果您的表包含这些属性，最好的做法是不启用表管理。

分区的限制

• 从开源引擎创建或注册表时，受管功能仅支持对 DATE、DATETIME 和 TIMESTAMP 字段类型进行分区，并使用 hour、day、month 和 year 转换（DATE 字段上的 hour 转换除外）以及 INTEGER 字段类型。
• 具有 IDENTITY 转换的表不支持受管理的容量。 用户必须明确指定转换。
• 如果表具有受管理的功能，则只有当 CREATE OR REPLACE 命令使用相同的分区规范时，才支持这些命令。不支持以下替换：
  • 将非分区表替换为分区表。
  • 将分区表替换为非分区表。
  • 将分区表替换为使用其他分区规范的表。
• 不支持自定义分区字段命名。通过开源引擎创建或注册的表必须遵循引擎的默认分区字段命名惯例（附加 _ 和转换名称，例如 _hour、_day、_month 或 _year）。例如，对于使用 DAY 转换且名为 time_date 的字段，预期的分区字段值为：json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

自定义 Iceberg 表属性的限制

启用受管理的功能后，以下表格行为属性无法配置为非默认值。如果启用了任何受管理的功能，系统会硬编码默认值：

从开源引擎创建或更改表时，可以配置以下属性：

其他 Apache Iceberg 写入属性（例如 write.target-file-size-bytes 和 write.parquet.page-size-bytes）可以通过开源引擎进行配置，但 BigQuery 写入和表管理作业可能不符合这些属性。

后续步骤

• 了解如何使用 BigQuery DML 修改数据。
• 了解如何查询表。