Configura las opciones de la tabla

Configurar las opciones de tabla te permite habilitar la interoperabilidad de escritura de BigQuery o la administración de tablas (optimización automática del almacenamiento) para tus tablas de Apache Iceberg en el catálogo de tiempo de ejecución de Lakehouse. Estas opciones sirven como parámetros de configuración fundamentales que extienden las capacidades para las operaciones en la tabla.

Si configuras propiedades de tabla específicas, puedes habilitar la interoperabilidad de escritura con BigQuery DML o la administración automática de tablas (optimización del almacenamiento).

Cuando usas tablas en el catálogo de tiempo de ejecución de Lakehouse, es útil comprender los diferentes tipos de tablas y sus capacidades de habilitación. Para obtener más información sobre el uso de tablas de Apache Iceberg específicamente, consulta Descripción general de las tablas de Apache Iceberg.

Antes de comenzar

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

  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

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

Roles obligatorios

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

  • Configurar las propiedades de la tabla en el modo de venta de credenciales: Editor de BigLake (roles/biglake.editor) - el proyecto
  • Configurar las propiedades de la tabla en el modo de venta de 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 mediante roles personalizados o cualquier otro rol predefinido.

Consideraciones sobre la configuración

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

Tablas de Iceberg compatibles

Solo se admiten las tablas de Apache Iceberg V2 (DG) y V3 (versión preliminar). No se admiten las tablas de Iceberg V1. 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 automática de tablas, tu catálogo de tiempo de ejecución 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 venta de credenciales para autenticar y actualizar los archivos de datos de almacenamiento subyacentes.

Habilita BigQuery DML

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

Las sentencias admitidas incluyen INSERT, UPDATE, DELETE y MERGE, así como sentencias DDL estándar como CREATE TABLE, ALTER TABLE y DROP TABLE, excepto las que no son compatibles con las tablas de Apache Iceberg en BigQuery.

Habilita BigQuery DML para tablas nuevas

Cuando creas una tabla desde BigQuery, BigQuery DML y la administración automática de tablas están habilitados de forma predeterminada. Cuando creas una tabla desde motores de código abierto, configura la propiedad de tabla gcp.biglake.bigquery-dml.enabled = true con la sintaxis 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 BigQuery DML para 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 BigQuery DML

Si inhabilitas BigQuery DML, la tabla se vuelve de solo lectura para BigQuery y se detiene la administración automática de tablas.

Por ejemplo, en Spark SQL:

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

Habilita 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 el borrado 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 del archivo metadata.json y, luego, borra físicamente los archivos de datos y metadatos que pertenecían solo a las instantáneas vencidas y que ya no hacen referencia a ninguna instantánea activa.

    • Limitación: Se omite el vencimiento de instantáneas y la recolección de elementos no utilizados asociada si la tabla usa etiquetas o ramas. Para obtener más información, consulta Limitaciones.

    • Limitación: La administración automática 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 mediante la combinación de archivos pequeños en archivos más grandes. Coalesce 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 coalesce produce una nueva instantánea de la tabla. Por lo general, los trabajos de coalesce ceden y vuelven a intentarlo después de cualquier operación DML en ejecución. Sin embargo, para evitar la inanición indefinida de la optimización del almacenamiento, se activa un trabajo de coalesce de forma forzada cada 24 horas si los datos son aptos para coalesce.

  • Supervisión de 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 jobs.

    La frecuencia de los trabajos de administración de tablas se relaciona directamente con la actividad de mutación de datos. Las inserciones o actualizaciones pequeñas y frecuentes activan tareas en segundo plano más frecuentes. 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.

Habilita la administración de tablas para tablas nuevas

Cuando creas una tabla desde BigQuery, DML y la administración automática de tablas están habilitados de forma predeterminada. Cuando creas una tabla desde motores de código abierto, configura la propiedad gcp.biglake.table-management.enabled. Si habilitas la administración de tablas, se habilita automáticamente BigQuery DML 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 tablas para tablas existentes

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

Por ejemplo, en Spark SQL:

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

Inhabilita la administración de tablas

Si inhabilitas la administración de tablas, se impide que se pongan en cola los trabajos de optimización en segundo plano futuros, aunque se completarán los trabajos activos en curso. Si inhabilitas la administración de tablas, no se inhabilita 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");

Limitaciones

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

Limitaciones generales

  • Las capacidades administradas solo son compatibles con las tablas de Apache Iceberg creadas en el catálogo de tiempo de ejecución de Lakehouse con el extremo del catálogo REST de Apache Iceberg.
  • Todas las limitaciones existentes para las tablas de Apache Iceberg administradas por BigQuery se aplican a las operaciones con las capacidades administradas habilitadas.
  • Las capacidades administradas no son compatibles con las tablas con la versión 3 del formato de Apache Iceberg. Solo se pueden habilitar las capacidades administradas para las tablas con la versión 2 del formato (especificación de Iceberg v2).
  • Las capacidades administradas no son compatibles con las tablas que tienen particiones avanzadas, como la partición por STRING, la partición de varias columnas o la evolución de particiones.
  • Las capacidades administradas no son compatibles con las tablas configuradas con órdenes de clasificación (por ejemplo, con el procedimiento WRITE ORDER BY o la configuración de write.distribution.mode = range).
  • Las capacidades administradas no son compatibles con las tablas de Iceberg v2 que usan el modo de combinación en lectura. Solo se pueden habilitar las capacidades administradas para las tablas que usan el modo de actualización, borrado y combinación de copia en escritura.
  • Las capacidades administradas no admiten archivos de datos comprimidos con códecs gzip, lz4 o brotli (write.parquet.compression.codec). Solo se admiten los tipos de compresión zstd y snappy para los archivos de datos.
  • Las capacidades 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 con 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 contener 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 NUMERIC tipo de datos en BigQuery, fallará cualquier actualización de esquema de Spark porque Spark lee NUMERIC como NUMERIC(38,9). Como solución alternativa, cuando crees tablas con el tipo NUMERIC en BigQuery, establece explícitamente 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 inmediatamente de la adición de una columna con el mismo nombre.

Limitaciones con el viaje en el tiempo

  • Cuando la administración de tablas está habilitada, el valor máximo recomendado para la propiedad history.expire.max-snapshot-age-ms es de 7 días.
  • No se aplican las configuraciones de BigQuery a nivel del proyecto o del 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 instantáneas 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 se ignoran todos los valores establecidos para la history.expire.max-ref-age-ms propiedad. Los motores de código abierto aún pueden realizar el vencimiento de instantáneas.
  • La administración automática de tablas no vence los esquemas ni las especificaciones de partición. El archivo metadata.json conserva el historial completo de esquemas y especificaciones de partición, incluso si ninguna instantánea hace referencia a esos IDs de esquema.

  • La administración automática de tablas no limpia los archivos huérfanos creados por BigQuery o 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 la ordenación z ni la ordenación lineal. Si tu tabla contiene estas propiedades, no se garantiza que se mantenga el diseño después de que se ejecute coalesce. Si tus tablas contienen estas propiedades, la mejor acción es no habilitar la administración de tablas.

Limitaciones con la partición

  • Cuando se crean o registran tablas desde motores de código abierto, las capacidades administradas solo admiten la partición en tipos de campos DATE, TIMESTAMP, y TIMESTAMPTZ con transformaciones hour, day, month, y year(excepto la transformación hour en campos DATE).
  • Las capacidades administradas no son compatibles con las tablas con transformaciones IDENTITY. Los usuarios deben especificar explícitamente la transformación.
    • 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 tabla no particionada
    • Reemplazar una tabla particionada por una tabla que usa una especificación de partición diferente
  • No se admite el nombre de campo de partición personalizado. 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 (agregar _ y el nombre de la transformación, como _hour, _day, _month, o _year). Por ejemplo, para un campo llamado time_date que usa la transformación DAY, el valor esperado del campo de partición es: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Limitaciones con las propiedades de tabla de Iceberg personalizadas

Las siguientes propiedades de comportamiento de la tabla no se pueden configurar en valores no predeterminados cuando se habilitan las capacidades administradas. Los valores predeterminados están codificados cuando se habilita cualquier capacidad administrada:

Propiedad Valor predeterminado Detalles
format-version 2 Las capacidades 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 Se usa la ruta de acceso predeterminada del bucket de Cloud Storage configurada para el catálogo REST de Lakehouse para escribir archivos de datos.
write.metadata.path table location + /metadata Se usa la ruta de acceso predeterminada del bucket de Cloud Storage configurada para el catálogo REST de Lakehouse 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 que no entran en conflicto) hacen que la transacción simultánea falle y vuelva a intentarlo.
write.update.isolation-level Detección estricta de conflictos El mismo comportamiento que write.delete.isolation-level.
write.merge.isolation-level Detección estricta de conflictos El mismo comportamiento que write.delete.isolation-level.

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

Propiedad Valor predeterminado Detalles
write.parquet.compression-codec zstd Las escrituras de BigQuery y la optimización del almacenamiento solo admiten 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 como null o gzip.
history.expire.max-snapshot-age-ms 432000000 (5 días) Se puede configurar en cualquier número entero positivo, pero se recomienda hasta 7 días (604800000 ms) cuando la administración de tablas está habilitada. Los trabajos de administración de tablas borran las instantáneas más antiguas que la duración especificada.
history.expire.min-snapshots-to-keep 1 Se puede configurar en cualquier número entero positivo. Los trabajos de administración de tablas conservan al menos esta cantidad de instantáneas.

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

¿Qué sigue?