通过配置表选项，您可以选择为 Lakehouse 运行时目录中的 Apache Iceberg 表启用 BigQuery 写入互操作性或表管理（自动存储优化）。 这些选项充当基础设置，可扩展表操作的功能。
通过配置特定的表属性，您可以启用与 BigQuery DML 的写入互操作性，或启用自动表管理（存储优化）。
在 Lakehouse 运行时目录中使用表时，了解不同的表类型及其选择启用功能会很有帮助。如需详细了解如何专门使用 Apache Iceberg 表，请参阅 Apache Iceberg 表概览。
准备工作
-
验证是否已为您的 Google Cloud 项目启用结算功能。
-
启用 BigLake API。
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，该角色包含serviceusage.services.enable权限。了解如何授予角色。 - 使用 Apache Iceberg REST Catalog 端点设置 Lakehouse 运行时 目录。
所需角色
如需获得配置表选项所需的权限，请让管理员向您授予项目的以下 IAM 角色和存储桶：
-
在 凭证自动售卖模式下配置表属性：
项目的 BigLake Editor (
roles/biglake.editor) 角色 -
在非凭证自动售卖模式下配置表属性：
- 项目的 BigLake Editor (
roles/biglake.editor) 角色 - Cloud Storage 存储桶的 Storage Object User (
roles/storage.objectUser) 角色
- 项目的 BigLake Editor (
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。
配置注意事项
配置表选项时，请考虑以下要求和默认行为：
支持的 Iceberg 表
仅支持 Apache Iceberg V2（正式版）和 V3（预览版）表。不支持 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过期。它会从metadata.json文件中移除过期的快照条目，然后物理删除仅属于过期快照且不再被任何实时快照引用的数据和元数据文件。合并（压缩）： 合并负责通过将小文件合并为大文件来维护数据的形状。合并会在任何数据突变后自动在后台运行。如果文件的平均未压缩大小小于目标文件大小 256 MB 的 50%，则会选择这些文件进行压缩。每次合并操作都会生成新的表快照。合并作业通常会在任何正在运行的 DML 操作之后让步并重试。但是，为防止存储 优化无限期停滞，如果数据 符合合并条件，则每 24 小时会强制触发一次合并作业。
监控表管理作业： 所有后台表管理作业都会记录在 BigQuery 的
INFORMATION_SCHEMA.JOBS视图中。您可以查询此视图来跟踪这些操作，类似于监控其他 BigQuery 作业的方式。如需详细了解如何查询作业 信息，请参阅获取 Iceberg 存储优化 作业。表管理作业的频率与数据突变活动直接相关。频繁的小型插入或更新会触发更频繁的后台任务。如果表没有写入操作，您可能会观察到没有后台作业的周期。相反，大量写入可能会导致
INFORMATION_SCHEMA中出现更多可见的作业活动。
为新表启用表管理
从 BigQuery
创建表时，系统会默认启用 DML 和自动表管理。从开源引擎创建表时，请配置 gcp.biglake.table-management.enabled 属性。如果尚未启用 BigQuery DML，启用表管理会自动启用 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。
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)。 - 已知问题： 不支持在 BigQuery 中使用 DDL (
ALTER TABLE ... DROP COLUMN) 删除列，然后立即重新添加具有相同名称的列。
时间旅行的限制
- 启用表管理后，
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）。合并不支持 z 排序和线性排序。如果您的表包含这些属性，则无法保证在合并运行后保留布局。如果您的表包含这些属性，最好的做法是不启用表管理。
分区的限制
- 从开源引擎创建或注册表时，托管
功能仅支持对
DATE、TIMESTAMP和TIMESTAMPTZ字段类型进行分区，并使用hour、day、month和year转换 （DATE字段上的hour转换除外）。 - 托管功能不支持具有
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 |
为 Lakehouse REST Catalog 配置的默认 Cloud Storage 存储桶路径用于写入数据文件。 |
write.metadata.path |
table location + /metadata |
为 Lakehouse REST Catalog 配置的默认 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 写入和表管理作业可能不符合这些属性。