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

Los vectores de eliminación binarios en las tablas de Apache Iceberg V3 te permiten registrar eliminaciones a nivel de fila en archivos .puffin sin volver a escribir archivos de datos completos. En lugar de realizar uniones costosas en el momento de la consulta, los motores como BigQuery, Managed Service para Apache Spark, Apache Flink y Trino usan estos vectores para identificar y omitir las filas borradas durante las lecturas.

Esta optimización, que se admite en el catálogo de entorno de ejecución de Lakehouse, puede mejorar el rendimiento de escritura y lectura para las canalizaciones de captura de datos modificados (CDC) de alto volumen. También te ayuda a cumplir con los requisitos reglamentarios, como el RGPD (derecho al olvido), ya que borra los registros individuales sin la sobrecarga de volver a escribir los archivos de datos.

Antes de comenzar

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

  2. Habilita la API de BigLake si aún no está habilitada.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén 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:

  • Crea y administra tablas de Iceberg V3:
    • Administrador de BigLake (roles/biglake.admin): tu proyecto
    • Administrador de almacenamiento (roles/storage.admin): 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. Asegúrate de crear correctamente el espacio de nombres y el catálogo antes de continuar.

Limitaciones

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

  • Nuevos tipos de datos de V3: No se admiten los nuevos tipos de datos de Iceberg V3 (como Variant, Geography, marca de tiempo de nanosegundos, valores predeterminados y tipos de datos desconocidos).
  • Seguimiento del linaje de filas: No se admite el seguimiento del linaje de filas.
  • Escrituras de BigQuery: Las escrituras de BigQuery no son compatibles con las tablas de la versión 3. Solo puedes leer tablas V3 desde BigQuery. Para crear tablas de la versión 3 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 la sesión de la tabla y 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 las eliminaciones se escriban en archivos separados (los vectores de eliminación) en lugar de volver a escribir 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 establece 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 de tu 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, propagar la tabla 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 que especifique format-version='3' y los modos de borrado, actualización y combinación de merge-on-read en las propiedades de la tabla. Ejecuta la siguiente sentencia 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 de la versión 2 a la 3

Puedes actualizar una tabla de Iceberg V2 existente a la versión V3 con las declaraciones ALTER TABLE. No se admite cambiar una tabla de la versión 3 a la 2. Ejecuta la siguiente sentencia 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 que haya 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. Ejecuta las siguientes sentencias en Spark SQL para propagar la tabla:

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 sentencia DELETE en Spark SQL. Debido a 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 sentencia UPDATE en Spark SQL. Debido a 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 binarios

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

Verifica si hay 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 las instantáneas

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 archivos de eliminación.

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

¿Qué sigue?