您可以使用 Lakehouse 运行时目录中的表选项，为 Apache Iceberg 表选择启用 BigQuery DML 写入互操作性和表管理（自动存储优化）。
如需详细了解 Lakehouse 运行时目录中支持的表格式和选择启用功能，请参阅比较表类型和 Apache Iceberg 表概览。
准备工作
-
启用 BigLake API（如果尚未启用）。
启用 API 所需的角色
如需启用 API，您需要拥有
serviceusage.services.enable权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。 - 使用 Apache Iceberg REST 目录端点设置 Lakehouse 运行时目录。
所需的角色
如需获得配置表选项所需的权限，请让管理员向您授予项目和存储桶的以下 IAM 角色：
-
在凭据自动售卖模式下配置表属性：BigLake Editor (
roles/biglake.editor) - 项目 -
在非凭证自动售卖模式下配置表属性：
- BigLake Editor (
roles/biglake.editor) - 项目 - Storage Object User (
roles/storage.objectUser) - 针对 Cloud Storage 存储桶
- BigLake Editor (
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
配置注意事项
配置表选项时，请考虑以下要求和默认行为：
支持的 Iceberg 表
虽然 Lakehouse 运行时目录支持 Apache Iceberg V2（正式版）和 V3（预览版）表，但托管功能（BigQuery DML 和表管理）仅支持 Iceberg V2 表。不支持 Iceberg V1 表。如需升级现有 V1 表，请参阅将 Iceberg V1 表升级到 V2。
凭证分发要求
如需选择启用表管理功能，您的 Lakehouse 运行时目录必须在目录级层启用凭证发放。表管理后台作业使用凭据发放服务账号来对底层存储数据文件进行身份验证和更新。
启用 BigQuery DML
启用 BigQuery 数据操纵语言 (DML) 语句后，即可在 BigQuery 中对使用开源引擎创建的 Apache Iceberg 表执行写入操作。
支持的语句包括 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中出现更多可见的作业活动。
选择是否启用桌台管理
对于由 Lakehouse 运行时目录管理并通过 Apache Iceberg REST 目录端点提供服务的 Apache Iceberg 表，您可以启用表管理，也可以使用开源或第三方引擎自行管理表维护（例如压缩和快照过期）。
在满足以下所有条件时，启用表管理 (gcp.biglake.table-management.enabled = true)：
您希望在 DML 或开源流式写入后自动执行后台文件压缩（合并）以及自动执行快照过期和垃圾回收。
您的目录使用凭证分发模式。
快照保留和时间旅行窗口最长可达 7 天（默认为 5 天），满足您的要求。
您的表符合托管功能的要求（请参阅限制）。
如果满足以下任一条件，请保持停用表管理功能（通过开源引擎创建的表的默认设置，或设置 gcp.biglake.table-management.enabled = false），并自行管理表维护：
您在 Apache Spark、Apache Flink 或 Trino 等开源引擎中运行自定义压缩或维护过程，尤其是在表依赖于合并操作无法保留的 Z 排序或线性排序布局时。
您的表使用 Apache Iceberg 快照标记或分支（这会导致表管理跳过快照过期），或者需要快照保留和时间旅行超过 7 天。
您的目录使用最终用户凭据（直接 Cloud Storage Identity and Access Management (IAM) 权限），而不是凭据分发模式。
您的表使用了托管功能不支持的功能（在这种情况下，表管理和 BigQuery DML 都必须保持停用状态），例如 Apache Iceberg 格式版本 3、读取时合并模式、多列或
IDENTITY分区，或自定义数据和元数据存储路径。如需查看不受支持的功能的完整列表，请参阅限制。
为新表启用表管理功能
当您通过 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
ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");
停用表格管理功能
停用表管理功能后，系统不会将未来的后台优化作业加入队列，但正在进行的活跃作业会完成。停用表管理不会停用 BigQuery DML。
Spark SQL
ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);
BigQuery
ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");
限制
托管式功能（例如 BigQuery 写入互操作性和表管理）的限制包括：
一般限制
- 只有使用 Apache Iceberg REST Catalog 端点在 Lakehouse 运行时目录中创建的 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属性设置的所有值。开源引擎仍可执行快照过期。 - 表管理不会使架构或分区规范过期。
metadata.json文件会保留架构和分区规范的完整历史记录，即使没有快照引用这些架构 ID 也是如此。 表管理功能不会清理 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 表属性的限制
启用代管式功能后，无法将以下表行为属性配置为非默认值。启用任何代管式功能时，默认值都会硬编码：
| 属性 | 默认值 | 详细信息 |
|---|---|---|
format-version |
2 |
托管式功能仅支持 Iceberg v2 表。 |
write.format.default |
parquet |
表仅支持 Parquet 格式的数据文件。 |
write.data.path |
table location + /data |
为 Apache Iceberg REST 目录端点配置的默认 Cloud Storage 存储桶路径用于写入数据文件。 |
write.metadata.path |
table location + /metadata |
为 Apache Iceberg REST 目录端点配置的默认 Cloud Storage 存储桶路径用于写入元数据文件。 |
write.delete.mode |
copy-on-write |
BigQuery 写入和表管理作业仅支持写入时复制。 |
write.update.mode |
copy-on-write |
BigQuery 写入和表管理作业仅支持写入时复制。 |
write.merge.mode |
copy-on-write |
BigQuery 写入和表管理作业仅支持写入时复制。 |
write.delete.isolation-level |
严格冲突检测 | 修改 metadata.json 文件的更改（包括数据冲突、元数据冲突、幻读或非冲突并发写入）会导致并发事务失败并重试。 |
write.update.isolation-level |
严格冲突检测 | 行为与 write.delete.isolation-level 相同。 |
write.merge.isolation-level |
严格冲突检测 | 行为与 write.delete.isolation-level 相同。 |
从开源引擎创建或更改表时，可以配置以下属性：
| 属性 | 默认值 | 详细信息 |
|---|---|---|
write.parquet.compression-codec |
zstd |
BigQuery 写入和存储优化仅支持 zstd 和 snappy 压缩格式。不支持其他压缩格式（例如 gzip、brotli 和 lz4）。 |
write.metadata.compression-codec |
null |
可配置为 null 或 gzip。 |
history.expire.max-snapshot-age-ms |
432000000（5 天） |
可配置为任何正整数，但启用表管理功能后，建议最长设置为 7 天（604800000 毫秒）。表管理作业会删除存在时间超过指定时长的快照。 |
history.expire.min-snapshots-to-keep |
1 |
可配置为任意正整数。表管理作业至少会保留此数量的快照。 |
其他 Apache Iceberg 写入属性（例如 write.target-file-size-bytes 和 write.parquet.page-size-bytes）可以通过开源引擎进行配置，但 BigQuery 写入和表管理作业可能不符合这些属性。
后续步骤
- 了解如何使用 BigQuery DML 修改数据。
- 了解如何查询表。