在 Iceberg V3 表中使用二进制删除向量

Lakehouse 运行时目录支持 Apache Iceberg V3 表。Apache Iceberg V3 规范的一项核心功能是二进制删除向量。此优化会将行级删除操作存储在 .puffin 文件中。BigQuery 和开源引擎（例如 Apache Spark、Apache Flink 和 Trino）不会在查询时执行开销巨大的联接，而是使用这些向量快速识别并跳过已删除的行。

使用二进制删除向量可以通过以下方式提升性能：

  • 大容量写入：提高大容量写入表的写入性能。
  • 高效读取：通过允许 BigQuery 和开源引擎识别并跳过已删除的行，提高查询速度。

这对于在更改数据捕获 (CDC) 流水线中处理大量更新和删除操作，或者通过删除特定行来满足 GDPR（被遗忘权）等监管要求非常有用，而无需重写整个数据文件，从而减少开销。

准备工作

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

  2. 启用 BigLake API。

    启用 API 所需的角色

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

    启用 API

所需的角色

如需获得创建和管理 Iceberg V3 表所需的权限，请让您的管理员为您授予项目和存储桶的以下 IAM 角色：

  • 创建和管理 Iceberg V3 表：
    • BigLake Admin (roles/biglake.admin) - 您的项目
    • Storage Admin (roles/storage.admin) - 目标 Cloud Storage 存储桶

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

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

设置 Iceberg REST Catalog

在创建 Iceberg V3 表之前，您必须设置 Iceberg REST 目录，包括创建命名空间和目录。

设置 Iceberg REST Catalog 可能需要一些时间才能完成。 请确保您已成功创建命名空间和目录，然后再继续。

限制

Lakehouse 运行时目录中的 Iceberg V3 表具有以下限制：

  • 新的 V3 数据类型：不支持新的 Iceberg V3 数据类型（例如 Variant、Geography、纳秒时间戳、默认值和未知数据类型）。
  • 行级沿袭跟踪：不支持行级沿袭跟踪。
  • BigQuery 写入：V3 表不支持 BigQuery 写入。您只能从 BigQuery 读取 V3 表。如需创建 V3 表并向其中写入数据，您必须使用开源引擎（例如 Apache Spark、Apache Flink 或 Trino）。

引擎要求

确保您使用的引擎版本支持 Iceberg V3 和二进制删除向量。建议使用 Apache Spark 3.5 或更高版本。本指南中的示例使用 iceberg-spark-runtime-3.5_2.12:1.10.1。

配置表和引擎会话时，请确保：

  • 表格格式版本：必须设置为 format-version='3'。
  • 删除模式：必须设置为 merge-on-read。此模式可确保将删除操作写入单独的文件（删除向量），而不是重写原始数据文件（写入时复制）。

Spark 会话配置示例

以下配置可启用必要的 Iceberg 扩展程序并设置 REST 目录连接：

spark-sql \
    --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1,org.apache.iceberg:iceberg-gcp:1.10.1 \
    --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-gcp-bundle/1.10.1/iceberg-gcp-bundle-1.10.1.jar \
    --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
    --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
    --conf spark.sql.catalog.CATALOG_NAME.type=rest \
    --conf spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog \
    --conf spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH \
    --conf spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID \
    --conf spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager \
    --conf spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO \
    --conf spark.sql.defaultCatalog=CATALOG_NAME

替换以下内容：

  • CATALOG_NAME：Apache Iceberg REST 目录端点的名称。
  • WAREHOUSE_PATH：存储数据仓库的 Cloud Storage 文件夹的 URI，以 gs:// 开头。
  • PROJECT_ID：您的 Google Cloud 项目 ID。

使用二元删除向量

如需在 Apache Iceberg V3 表中使用二进制删除向量，您必须创建格式版本为 3 的表，使用数据填充该表，执行标准数据库修改，然后查询该表。您可以使用 Spark SQL 运行所有创建、插入、删除和更新语句。

创建具有二进制删除向量的 Iceberg 表

创建表，并在表属性中指定 format-version='3' 和 merge-on-read 删除、更新和合并模式。在 Spark SQL 中运行以下语句：

Spark 

CREATE NAMESPACE IF NOT EXISTS my_namespace;
USE my_namespace;

CREATE TABLE my_namespace.mytable_v3 (
   id BIGINT,
   city STRING,
   state STRING
) TBLPROPERTIES (
   'format-version'='3',
   'write.delete.mode'='merge-on-read',
   'write.update.mode'='merge-on-read'