Configura las opciones de la tabla

Configurar las opciones de la 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 del entorno de ejecución de Lakehouse. Estas opciones sirven como parámetros de configuración básicos que extienden las capacidades para las operaciones en la tabla.

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

Cuando se usan tablas en el catálogo del 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 específico de las tablas de Apache Iceberg, consulta 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 lo hiciste.

    Roles necesarios para habilitar las APIs

    Para habilitar 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 obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar la API

  3. Configura el catálogo de entornos 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 no 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 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

Solo se admiten las tablas de Apache Iceberg V2 (GA) y V3 (versión preliminar). No se admiten las tablas de Iceberg V1. Para actualizar las tablas de la versión 1 existentes, consulta Actualiza las tablas de Iceberg de la versión 1 a la versión 2.

Requisito de venta de credenciales

Para habilitar la administración automática de tablas, tu catálogo de entorno 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 autenticarse y actualizar los archivos de datos de almacenamiento subyacentes.

Habilita el DML de BigQuery

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

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

Habilita el DML de BigQuery para tablas nuevas

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

Si inhabilitas el DML de BigQuery, la tabla será de solo lectura para BigQuery y se detendrá la administración automática 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 más que se manifiesta en un nuevo archivo de metadatos que ya no incluye referencias a las instantáneas que se quitaron.

    • Limitación: Se omiten la fecha de vencimiento de la instantánea 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, ya que combina 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 combinación produce una nueva instantánea de la tabla. Por lo general, los trabajos de coalescencia ceden y vuelven a intentarlo después de cualquier operación de DML en ejecución. Sin embargo, para evitar la inanición indefinida de la optimización del almacenamiento, se activa un trabajo de coalescencia de forma forzada cada 24 horas si los datos son aptos para la coalescencia.

  • Trabajos de administración de tablas de supervisión: 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 del 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 más frecuentes. Es posible que observes períodos sin trabajos en segundo plano si no se realizan 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 las tablas nuevas

Cuando crea una tabla desde BigQuery, el DML y la administración automática de tablas se habilitan 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 tablas para las 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 evitará que se pongan en cola trabajos de optimización en segundo plano futuros, aunque se completarán 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 automática de tablas) incluyen lo siguiente:

Limitaciones generales

  • Las capacidades administradas solo se admiten con las tablas de Apache Iceberg creadas en el catálogo de entornos 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 capacidades administradas no son compatibles con las tablas con la versión 3 del formato de Apache Iceberg. Solo las tablas con la versión de formato 2 (especificación de Iceberg v2) pueden habilitar las capacidades administradas.
  • 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 se admiten para las tablas configuradas con órdenes de clasificación (por ejemplo, con el procedimiento WRITE ORDER BY o el parámetro de configuración write.distribution.mode = range).
  • Las capacidades administradas no son compatibles con las tablas de Iceberg v2 que usan el modo de combinación en la lectura. Solo las tablas que usan el modo de actualización, eliminación y combinación de copiar al escribir se pueden habilitar para las capacidades administradas.
  • Las funciones administradas no admiten archivos de datos comprimidos con los 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 o campos anidados en una estructura.
  • Las capacidades administradas no son compatibles con las tablas que tienen ubicaciones de metadatos o datos personalizados (write.data.path y write.metadata.path). Se requiere la ubicación predeterminada del bucket de Cloud Storage para almacenar 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 del entorno de ejecución de Lakehouse.
  • Si se crea una tabla con el tipo de datos NUMERIC en BigQuery, fallará cualquier actualización del esquema desde Spark, ya que Spark lee NUMERIC como NUMERIC(38,9). Como solución alternativa, cuando crees tablas con el tipo NUMERIC en BigQuery, establece la precisión de forma explícita 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 reincorporación de una columna con el mismo nombre.

Limitaciones con la función de 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 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 configuración de retención personalizada establecida con ALTER... RETAIN x DAYS, y se ignoran los valores establecidos para la propiedad history.expire.max-ref-age-ms. Los motores de código abierto aún pueden realizar el vencimiento de instantáneas.
  • La administración automática 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 automática 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 Spark remove_orphan_files 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 el diseño se mantenga después de que se ejecute la combinación. Si tus tablas contienen estas propiedades, lo mejor es no habilitar 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 las transformaciones hour, day, month y year (excepto la transformación hour en los campos DATE) y los tipos de campos INTEGER.
  • Las capacidades administradas no son compatibles con las tablas que tienen 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 uso de nombres personalizados para los campos de partición. Las tablas creadas o registradas desde motores de código abierto deben seguir la convención de nomenclatura predeterminada del campo de partición 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 el siguiente: 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 las capacidades administradas están habilitadas. 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 La ruta de acceso predeterminada del bucket de Cloud Storage configurada para el extremo del catálogo 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 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 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.

Se pueden configurar las siguientes propiedades cuando se crean o modifican tablas desde 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 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 que superan 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.

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 los trabajos de escritura y administración de tablas de BigQuery no las cumplan.

¿Qué sigue?