Usa vectores de eliminación binarios en las tablas de Iceberg V3

El catálogo del entorno de ejecución de Lakehouse admite tablas de Apache Iceberg V3. Una característica principal de la especificación de Apache Iceberg V3 son los vectores de eliminación binarios. Esta optimización almacena las eliminaciones a nivel de la fila en archivos .puffin. En lugar de realizar uniones costosas en el momento de la consulta, BigQuery y los motores de código abierto (como Apache Spark, Apache Flink y Trino) usan estos vectores para identificar y omitir rápidamente las filas borradas.

El uso de vectores de eliminación binarios puede mejorar el rendimiento de las siguientes maneras:

  • Escrituras de gran volumen: Mejora el rendimiento de escritura para las tablas con escrituras de gran volumen.
  • Lecturas eficientes: Mejoran la velocidad de las consultas, ya que permiten que BigQuery y los motores de código abierto identifiquen y omitan las filas borradas.

Esto es especialmente útil para controlar las actualizaciones y los borrados de gran volumen en las canalizaciones de captura de datos modificados (CDC) o para cumplir con los requisitos reglamentarios, como el RGPD (derecho al olvido), borrando filas específicas sin la sobrecarga de volver a escribir archivos de datos completos.

Antes de comenzar

  1. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  2. Habilita la API de BigLake.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la API

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar tablas de Iceberg V3, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto y bucket de almacenamiento:

  • Todos:
    • Administrador de BigLake (roles/biglake.admin): Tu proyecto
    • Administrador de almacenamiento (roles/storage.admin): Es el bucket de Cloud Storage de destino.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Configura el catálogo de REST de Iceberg

Antes de crear una tabla de Iceberg V3, debes configurar el catálogo de REST de Iceberg, lo que incluye crear un espacio de nombres y un catálogo.

La configuración del catálogo de REST de Iceberg puede tardar un tiempo en completarse. Antes de continuar, asegúrate de crear correctamente el espacio de nombres y el catálogo.

Limitaciones

Las tablas de Iceberg V3 en el catálogo de entorno de ejecución de Lakehouse tienen las siguientes limitaciones:

  • Nuevos tipos de datos de la versión 3: No se admiten los nuevos tipos de datos de Iceberg V3 (como Variant, Geography, Nanosecond timestamp, valores predeterminados y tipos de datos desconocidos).
  • Seguimiento del linaje de las filas: No se admite el seguimiento del linaje de las filas.
  • Escrituras de BigQuery: Las escrituras de BigQuery no son compatibles con las tablas de la versión 3. Solo puedes leer tablas de la versión 3 desde BigQuery. Para crear tablas V3 y escribir en ellas, debes usar motores de código abierto (como Apache Spark, Apache Flink o Trino).

Requisitos del motor

Asegúrate de usar una versión del motor que admita Iceberg V3 y vectores de eliminación binarios. Se recomienda Apache Spark 3.5 o una versión posterior. En los ejemplos de esta guía, se usa iceberg-spark-runtime-3.5_2.12:1.10.1.

Cuando configures tu tabla y la sesión del motor, asegúrate de lo siguiente:

  • Versión del formato de tabla: Se debe establecer en format-version='3'.
  • Modo de eliminación: Debe establecerse en merge-on-read. Este modo garantiza que los borrados se escriban en archivos separados (los vectores de borrado) en lugar de reescribir los archivos de datos originales (copia en escritura).

Ejemplo de configuración de sesión de Spark

La siguiente configuración habilita las extensiones de Iceberg necesarias y configura la conexión del catálogo de 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

Reemplaza lo siguiente:

  • CATALOG_NAME: Es el nombre del extremo del catálogo de REST de Apache Iceberg.
  • WAREHOUSE_PATH: Es el URI de la carpeta de Cloud Storage en la que se almacena tu almacén de datos, que comienza con gs://.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .

Usa vectores de eliminación binarios

Para usar vectores de eliminación binarios en tablas de Apache Iceberg V3, debes crear una tabla con la versión de formato 3, propagarla con datos, realizar modificaciones estándar en la base de datos y consultar la tabla. Puedes ejecutar todas las instrucciones de creación, inserción, eliminación y actualización con Spark SQL.

Crea una tabla de Iceberg con vectores de eliminación binarios

Crea una tabla en la que se especifiquen format-version='3' y los modos de borrado, actualización y combinación merge-on-read en las propiedades de la tabla. Ejecuta la siguiente instrucción en 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',
   'write.merge.mode'='merge-on-read'
);

Actualiza una tabla de Iceberg V2 a V3

Puedes actualizar una tabla Iceberg V2 existente a la versión V3 con declaraciones ALTER TABLE. No se admite la degradación de una tabla de la versión 3 a la versión 2. Ejecuta la siguiente instrucción en Spark SQL:

Spark 

ALTER TABLE my_namespace.mytable_v2 SET TBLPROPERTIES ('format-version' = '3');

Inserta datos en la tabla

Para garantizar que se generen archivos de vectores de eliminación binarios para las eliminaciones, el motor no debe recurrir a la copia en escritura. Por lo general, esto requiere una cantidad significativa de datos en la tabla antes de la operación de eliminación. Por ejemplo, Apache Spark podría optimizar las eliminaciones pequeñas recurriendo a la copia en escritura. Para completar la tabla, ejecuta las siguientes instrucciones en Spark SQL:

Spark 

-- Create a temporary view with a large number of rows (100,000 rows)
CREATE OR REPLACE TEMPORARY VIEW large_source AS
SELECT
  id,
  CAST(id AS STRING) as city,
  'WA' as state
FROM (
  SELECT row_number() OVER (ORDER BY (SELECT NULL)) as id
  FROM (SELECT 0 FROM range(1000)) a
  CROSS JOIN (SELECT 0 FROM range(100)) b
);

-- Overwrite the existing table with the generated data
INSERT OVERWRITE my_namespace.mytable_v3 SELECT * FROM large_source;

Borra datos

Ejecuta una instrucción DELETE en Spark SQL. Dado que la tabla está configurada para merge-on-read y tiene suficientes datos, Spark genera archivos de eliminación con vectores de eliminación binarios.

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

Actualiza datos

Ejecuta una instrucción UPDATE en Spark SQL. Dado que la tabla está configurada para merge-on-read y tiene suficientes datos, Spark genera archivos de eliminación con vectores de eliminación binarios.

Spark 

UPDATE my_namespace.mytable_v3 SET state = 'NY' WHERE id = 1;

Consulta la tabla

Las consultas en la tabla usan automáticamente los archivos de vectores de eliminación binarios para excluir las filas borradas. Puedes consultar la tabla con Apache Spark o BigQuery.

Spark 

-- Should be less than the initial 100,000 rows
SELECT count(*) FROM my_namespace.mytable_v3;

-- Should return no results
SELECT * FROM my_namespace.mytable_v3 WHERE id = 5000;

-- Should return 'NY'
SELECT * FROM my_namespace.mytable_v3 WHERE id = 1;

BigQuery

Cuando realices consultas desde BigQuery, usa el identificador de tabla completamente calificado PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3.

bq query --nouse_legacy_sql \
    'SELECT * FROM `PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3` LIMIT 10'

Verifica la creación de vectores de eliminación de objetos binarios

Puedes verificar que los vectores de eliminación binarios se hayan creado correctamente inspeccionando el directorio de almacenamiento y los metadatos de la instantánea.

Cómo buscar archivos .puffin

Navega al directorio de datos de la tabla en tu almacén de Cloud Storage (por ejemplo, gs://WAREHOUSE_BUCKET/my_namespace/mytable_v3/data). Deberías encontrar archivos .puffin, que almacenan los vectores de eliminación binarios.

Examina los metadatos de la instantánea

Los metadatos de la instantánea en los archivos JSON de la tabla de Iceberg contienen información sobre la operación de eliminación. Busca propiedades como added-delete-files, added-dvs y operation en el resumen de la instantánea. Esto confirma que se agregaron los archivos de eliminación.

"summary": {
  "operation": "delete",
  "added-delete-files": "1",
  "added-dvs": "1",
  "added-files-size": "42",
  "added-position-deletes": "1",
  ...
}

¿Qué sigue?