Configura las opciones de la tabla

Puedes usar las opciones de tabla en el catálogo de tiempo de ejecución de Lakehouse para habilitar la interoperabilidad de escritura de DML de BigQuery y la administración de tablas (optimización automática del almacenamiento) para tus tablas de Apache Iceberg.

Para obtener más información sobre los formatos de tabla admitidos y las funciones de habilitación en el catálogo de tiempo de ejecución de Lakehouse, consulta Compara tipos de tablas y Descripción general de las tablas de Apache Iceberg.

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

  3. Configura el catálogo de tiempo de ejecución de Lakehouse con el extremo del catálogo de REST de Apache Iceberg.

Roles obligatorios

Para obtener los permisos que necesitas para configurar las opciones de la tabla, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto y bucket de almacenamiento:

  • Configura las propiedades de la tabla en el modo de venta de credenciales: Editor de BigLake (roles/biglake.editor): el proyecto
  • Configura las propiedades de la tabla en el modo de venta sin credenciales:
    • Editor de BigLake (roles/biglake.editor): el proyecto
    • Usuario de objetos de almacenamiento (roles/storage.objectUser): el bucket de Cloud Storage

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.

Consideraciones de configuración

Ten en cuenta los siguientes requisitos y comportamientos predeterminados cuando configures las opciones de la tabla:

Tablas de Iceberg compatibles

Aunque el catálogo de tiempo de ejecución de Lakehouse admite tablas de Apache Iceberg V2 (DG) y V3 (versión preliminar), las funciones administradas (DML de BigQuery y administración de tablas) solo se admiten para las tablas de Iceberg V2. Las tablas de Iceberg V1 no son compatibles. Para actualizar las tablas V1 existentes, consulta Actualiza las tablas de Iceberg V1 a V2.

Requisito de venta de credenciales

Para habilitar la administración de tablas, tu catálogo de Lakehouse debe tener habilitada la venta de credenciales a nivel del catálogo. Los trabajos en segundo plano de administración de tablas usan la cuenta de servicio de distribución de credenciales para autenticar y actualizar los archivos de datos de almacenamiento subyacentes.

Habilita DML de BigQuery

Habilitar las sentencias del lenguaje de manipulación de datos (DML) de BigQuery desbloquea la interoperabilidad de escritura de BigQuery en tablas de Apache Iceberg creadas con motores de código abierto.

Las declaraciones admitidas incluyen INSERT, UPDATE, DELETE y MERGE, así como las declaraciones de DDL estándar, como CREATE TABLE, ALTER TABLE y DROP TABLE, excepto aquellas que no se admiten en las tablas de Apache Iceberg en BigQuery.

Habilita DML de BigQuery para tablas nuevas

Cuando creas una tabla desde BigQuery, el DML de BigQuery y la administración de tablas están habilitados de forma predeterminada. Cuando crees una tabla a partir de motores de código abierto, configura la propiedad de tabla gcp.biglake.bigquery-dml.enabled = true con la sintaxis de DDL de tu motor.

Por ejemplo, en Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Habilita el DML de BigQuery para las tablas existentes

Para habilitar BigQuery DML en una tabla existente, actualiza la propiedad de la tabla.

Por ejemplo, en Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Inhabilita DML de BigQuery

Inhabilitar el DML de BigQuery hace que la tabla sea de solo lectura para BigQuery y detiene la administración de la tabla.

Por ejemplo, en Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

Habilitar la administración de tablas

La administración de tablas automatiza los procesos en segundo plano para optimizar el almacenamiento y administrar el ciclo de vida de los datos y los metadatos, como la compactación y la recolección de elementos no utilizados.

La administración de tablas te permite realizar las siguientes operaciones:

  • Vencimiento de instantáneas y recolección de elementos no utilizados: El vencimiento de instantáneas administra la retención y eliminación de archivos de datos y metadatos de las instantáneas de tablas. Esto se ejecuta automáticamente en segundo plano después de cualquier mutación de datos. Las instantáneas vencen según las propiedades de la tabla de Iceberg configuradas por el usuario history.expire.max-snapshot-age-ms y history.expire.min-snapshots-to-keep en la tabla. Quita las entradas de instantáneas vencidas creando una definición de instantánea adicional en un archivo de metadatos nuevo que omite las referencias a las instantáneas quitadas.

    • Limitación: El vencimiento de la instantánea y la recolección de elementos no utilizados asociada se omiten si la tabla usa etiquetas o ramas. Para obtener más información, consulta Limitaciones.

    • Limitación: La administración de tablas no controla la eliminación de archivos huérfanos. Para obtener más información, consulta Limitaciones.

  • Coalesce (compactación): Coalesce es responsable de mantener la forma de los datos, ya que combina archivos pequeños en archivos más grandes. La fusión se ejecuta automáticamente en segundo plano después de cualquier mutación de datos. Los archivos se seleccionan para la compactación si su tamaño promedio sin comprimir es inferior al 50% del tamaño de archivo objetivo de 256 MB. Cada operación de fusión produce una nueva instantánea de tabla. Los trabajos de fusión suelen ceder y reintentar después de cualquier operación de DML en ejecución. Sin embargo, para evitar la falta indefinida de optimización del almacenamiento, se activa un trabajo de fusión de forma forzosa cada 24 horas si los datos son aptos para la fusión.

  • Supervisa los trabajos de administración de tablas: Todos los trabajos de administración de tablas en segundo plano se registran en la vista INFORMATION_SCHEMA.JOBS de BigQuery. Puedes consultar esta vista para hacer un seguimiento de estas operaciones, de manera similar a como supervisas otros trabajos de BigQuery. Para obtener más información sobre cómo consultar información de trabajos, consulta Obtén trabajos de optimización de almacenamiento de Iceberg.

    La frecuencia de los trabajos de administración de tablas se correlaciona directamente con la actividad de mutación de datos. Las inserciones o actualizaciones pequeñas y frecuentes activan tareas en segundo plano con mayor frecuencia. Es posible que observes períodos sin trabajos en segundo plano si no hay escrituras en la tabla. Por el contrario, los volúmenes de escritura altos pueden generar una actividad de trabajo más visible en INFORMATION_SCHEMA.

Elige si quieres habilitar la administración de mesas

En el caso de las tablas de Apache Iceberg administradas por el catálogo de tiempo de ejecución de Lakehouse y entregadas a través del extremo del catálogo de REST de Apache Iceberg, puedes habilitar la administración de tablas o administrar el mantenimiento de las tablas (como la compactación y el vencimiento de las instantáneas) por tu cuenta con motores de código abierto o de terceros.

Habilita la administración de tablas (gcp.biglake.table-management.enabled = true) cuando se cumplan todas las condiciones siguientes:

  • Deseas una compactación de archivos en segundo plano automatizada (coalescencia), un vencimiento de instantáneas automatizado y una recolección de elementos no utilizados después de las escrituras de transmisión de código abierto o DML.

  • Tu catálogo usa el modo de venta de credenciales.

  • Una ventana de retención de instantáneas y de viaje en el tiempo de hasta 7 días (5 días de forma predeterminada) cumple con tus requisitos.

  • Tu tabla cumple con los requisitos para las funciones administradas (consulta Limitaciones).

Mantén inhabilitada la administración de tablas (la opción predeterminada para las tablas creadas a partir de motores de código abierto o establece gcp.biglake.table-management.enabled = false) y administra el mantenimiento de las tablas por tu cuenta cuando se aplique alguna de las siguientes condiciones:

  • Ejecutas procedimientos personalizados de compactación o mantenimiento en motores de código abierto, como Apache Spark, Apache Flink o Trino, en especial si tus tablas dependen de diseños de ordenamiento lineal o de ordenamiento Z que la fusión no conserva.

  • Tus tablas usan etiquetas o ramas de instantáneas de Apache Iceberg (que hacen que la administración de tablas omita el vencimiento de las instantáneas) o requieren la retención de instantáneas y el viaje en el tiempo durante más de 7 días.

  • Tu catálogo usa credenciales de usuario final (permisos directos de Identity and Access Management (IAM) de Cloud Storage) en lugar del modo de venta de credenciales.

  • Tus tablas usan funciones que no son compatibles con las capacidades administradas (en cuyo caso, tanto la administración de tablas como el DML de BigQuery deben permanecer inhabilitados), como la versión 3 del formato de Apache Iceberg, el modo de combinación en lectura, la partición de varias columnas o IDENTITY, o las rutas de acceso de almacenamiento de datos y metadatos personalizadas. Para obtener una lista completa de las funciones no compatibles, consulta Limitaciones.

Habilita la administración de tablas para las tablas nuevas

Cuando creas una tabla desde BigQuery, el DML y la administración de tablas están habilitados de forma predeterminada. Cuando creas una tabla a partir de motores de código abierto, configura la propiedad gcp.biglake.table-management.enabled. Si habilitas la administración de tablas, se habilitará automáticamente el DML de BigQuery si aún no está habilitado.

Por ejemplo, en Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Habilita la administración de mesas para las mesas existentes

Para habilitar la administración de tablas en una tabla existente, actualiza la propiedad de la tabla.

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");

Inhabilitar la administración de tablas

Inhabilitar la administración de tablas evita que se pongan en cola los trabajos de optimización en segundo plano futuros, aunque se completen los trabajos activos en curso. Inhabilitar la administración de tablas no inhabilita el DML de BigQuery.

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");

Limitaciones

Las limitaciones de las capacidades administradas (como la interoperabilidad de escritura de BigQuery y la administración de tablas) incluyen las siguientes:

Limitaciones generales

  • Las funciones administradas solo se admiten con tablas de Apache Iceberg creadas en el catálogo de tiempo de ejecución de Lakehouse con el extremo del catálogo de REST de Apache Iceberg.
  • Todas las limitaciones existentes para las tablas de Apache Iceberg administradas por BigQuery se aplican a las operaciones con capacidades administradas habilitadas.
  • Las funciones administradas no son compatibles con las tablas que tienen la versión 3 del formato de Apache Iceberg. Solo las tablas de la versión de formato 2 (especificación de Iceberg v2) se pueden habilitar para las funciones administradas.
  • Las capacidades administradas no se admiten en las tablas que tienen particionamiento avanzado, como el particionamiento por STRING, el particionamiento de varias columnas o la evolución de particiones.
  • Las capacidades administradas no se admiten en las tablas configuradas con órdenes de clasificación (por ejemplo, con el procedimiento WRITE ORDER BY o la configuración write.distribution.mode = range).
  • Las funciones administradas no son compatibles con las tablas de Iceberg v2 que usan el modo de combinación en lectura. Solo las tablas que usan el modo de actualización, eliminación y combinación de copia en escritura pueden habilitarse para las funciones administradas.
  • Las capacidades administradas no admiten archivos de datos comprimidos con códecs gzip, lz4 ni brotli (write.parquet.compression-codec). Solo se admiten los tipos de compresión zstd y snappy para los archivos de datos.
  • Las funciones administradas no son compatibles con las tablas si el esquema contiene identificadores de clave primaria anidados (identifier-field-ids) que hacen referencia a rutas de acceso o campos anidados en una estructura.
  • Las capacidades administradas no son compatibles con las tablas que tienen ubicaciones de datos o metadatos personalizadas (write.data.path y write.metadata.path). Se requiere la ubicación predeterminada del bucket de Cloud Storage para almacenar los archivos de datos y metadatos.
  • El agrupamiento en clústeres de BigQuery no es compatible con las tablas de Apache Iceberg administradas por el catálogo de tiempo de ejecución de Lakehouse.
  • Si se crea una tabla con el tipo de datos NUMERIC en BigQuery, cualquier actualización de esquema de Spark falla porque Spark lee NUMERIC como NUMERIC(38,9). Como solución alternativa, cuando crees tablas con el tipo NUMERIC en BigQuery, establece de forma explícita la precisión en NUMERIC(38,9).
  • Problema conocido: No se admite la eliminación de una columna en BigQuery con DDL (ALTER TABLE ... DROP COLUMN) seguida de inmediato por la acción de volver a agregar una columna con el mismo nombre.

Limitaciones de los viajes en el tiempo

  • Cuando se habilita la administración de tablas, el valor máximo permitido para la propiedad history.expire.max-snapshot-age-ms es de 30 días (2592000000 ms) y el valor máximo recomendado es de 7 días (604800000 ms). El valor máximo permitido para la propiedad history.expire.min-snapshots-to-keep es 100.
  • No se aplican las configuraciones de BigQuery a nivel de proyecto o de conjunto de datos para el viaje en el tiempo. Solo están activas las propiedades y los valores predeterminados de la tabla de Iceberg.

Limitaciones con la administración de tablas

  • Se omite el vencimiento de la instantánea para toda la tabla si esta contiene instantáneas con etiquetas o ramas. Se ignora la retención personalizada establecida con ALTER... RETAIN x DAYS y los valores establecidos para la propiedad history.expire.max-ref-age-ms. Los motores de código abierto aún pueden realizar la vencimiento de instantáneas.
  • La administración de tablas no hace que venzan los esquemas ni las especificaciones de partición. El archivo metadata.json conserva el historial completo de los esquemas y las especificaciones de partición, incluso si ninguna instantánea hace referencia a esos IDs de esquema.

  • La administración de tablas no limpia los archivos huérfanos creados por BigQuery o los motores de código abierto. Los motores de código abierto pueden realizar la limpieza de archivos huérfanos (por ejemplo, con el procedimiento remove_orphan_files de Spark con la opción prefix_listing establecida en true).

  • Coalesce no admite el ordenamiento en Z ni el ordenamiento lineal. Si tu tabla contiene estas propiedades, no se garantiza que se mantenga el diseño después de que se ejecute la fusión. Si tus tablas contienen estas propiedades, no habilites la administración de tablas.

Limitaciones de la partición

  • Cuando se crean o registran tablas desde motores de código abierto, las capacidades administradas solo admiten la partición en los tipos de campos DATE, DATETIME y TIMESTAMP con transformaciones hour, day, month y year (excepto la transformación hour en los campos DATE) y los tipos de campos INTEGER.
  • Las funciones administradas no son compatibles con las tablas que tienen transformaciones IDENTITY. Debes especificar la transformación de forma explícita.
  • Los comandos CREATE OR REPLACE en tablas con capacidades administradas solo se admiten si usan la misma especificación de partición. No se admiten los siguientes reemplazos:
    • Reemplazar una tabla no particionada por una tabla particionada.
    • Reemplazar una tabla particionada por una no particionada
    • Reemplazar una tabla particionada por una tabla que use una especificación de partición diferente
  • No se admite la asignación de nombres personalizados a los campos de partición. Las tablas creadas o registradas desde motores de código abierto deben seguir la convención de nombres de campo de partición predeterminada del motor (agregando _ y el nombre de la transformación, como _hour, _day, _month o _year). Por ejemplo, para un campo llamado time_date con la transformación DAY, el valor del campo de partición esperado es: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Limitaciones con las propiedades personalizadas de las tablas de Iceberg

Las siguientes propiedades de comportamiento de la tabla no se pueden configurar con valores no predeterminados cuando se habilitan las funciones administradas. Los valores predeterminados se codifican de forma rígida cuando se habilita cualquier capacidad administrada:

Propiedad Valor predeterminado Detalles
format-version 2 Las funciones administradas solo admiten tablas de Iceberg v2.
write.format.default parquet Las tablas solo admiten archivos de datos en formato Parquet.
write.data.path table location + /data La ruta predeterminada del bucket de Cloud Storage configurada para el extremo del catálogo de REST de Apache Iceberg se usa para escribir archivos de datos.
write.metadata.path table location + /metadata La ruta de acceso predeterminada del bucket de Cloud Storage configurada para el extremo del catálogo de REST de Apache Iceberg se usa para escribir archivos de metadatos.
write.delete.mode copy-on-write Los trabajos de escritura y administración de tablas de BigQuery solo admiten la copia en escritura.
write.update.mode copy-on-write Los trabajos de escritura y administración de tablas de BigQuery solo admiten la copia en escritura.
write.merge.mode copy-on-write Los trabajos de escritura y administración de tablas de BigQuery solo admiten la copia en escritura.
write.delete.isolation-level Detección estricta de conflictos Los cambios que modifican el archivo metadata.json (incluidos los conflictos de datos, los conflictos de metadatos, las lecturas fantasma o las escrituras simultáneas sin conflictos) hacen que la transacción simultánea falle y se vuelva a intentar.
write.update.isolation-level Detección estricta de conflictos Tiene el mismo comportamiento que write.delete.isolation-level.
write.merge.isolation-level Detección estricta de conflictos Tiene el mismo comportamiento que write.delete.isolation-level.

Las siguientes propiedades se pueden configurar cuando se crean o modifican tablas de motores de código abierto:

Propiedad Valor predeterminado Detalles
write.parquet.compression-codec zstd La optimización de escritura y almacenamiento de BigQuery solo admite los formatos de compresión zstd y snappy. No se admiten otros formatos de compresión (como gzip, brotli y lz4).
write.metadata.compression-codec null Se puede configurar en null o gzip.
history.expire.max-snapshot-age-ms 432000000 (5 días) Se puede configurar con cualquier número entero no negativo hasta 2592000000 (30 días) cuando la administración de tablas está habilitada, con un máximo recomendado de 7 días (604800000 ms). Los trabajos de administración de tablas borran las instantáneas que tienen más de la duración especificada.
history.expire.min-snapshots-to-keep 1 Se puede configurar en cualquier número entero positivo hasta 100 cuando la administración de tablas está habilitada. Los trabajos de administración de tablas conservan, al menos, esta cantidad de instantáneas.

Otras propiedades de escritura de Apache Iceberg, como write.target-file-size-bytes y write.parquet.page-size-bytes, se pueden configurar desde motores de código abierto, pero es posible que las escrituras de BigQuery y los trabajos de administración de tablas no las cumplan.

¿Qué sigue?