Accede a los datos de Iceberg desde AlloyDB

El acceso directo a Iceberg en AlloyDB para PostgreSQL te permite consultar datos almacenados en el formato de tabla de Apache Iceberg en Cloud Storage desde tu instancia de AlloyDB. Puedes acceder a los conjuntos de datos de Iceberg con los URIs de bucket de Cloud Storage o con el catálogo de tiempo de ejecución de Lakehouse. Para acelerar las cargas de trabajo analíticas, AlloyDB proporciona un motor de columnas integrado que optimiza los análisis, las uniones y las agregaciones. A través de la integración con el motor de columnas, el acceso directo a Iceberg te permite ejecutar consultas analíticas de alto rendimiento en tu data lakehouse sin compilar, administrar ni mantener canalizaciones de datos complejas de extracción, transformación y carga (ETL).

Puedes consultar tablas de Iceberg con comandos de SQL estándar, unir conjuntos de datos de Iceberg con tablas operativas en AlloyDB y propagar tablas de Iceberg en el motor de columnas en memoria para acelerar el rendimiento de las consultas.

Beneficios

El acceso directo a Iceberg proporciona los siguientes beneficios:

  • Acceso a lakehouse sin ETL: consulta conjuntos de datos externos de Iceberg in situ sin copiar ni mover datos a sistemas analíticos independientes.
  • Consultas transaccionales y analíticas unificadas: une datos operativos en vivo almacenados en tablas de montón de AlloyDB con datos históricos masivos almacenados en tablas de Iceberg en Cloud Storage.
  • Integración flexible de catálogos: accede a los metadatos de las tablas de Iceberg desde las rutas de acceso de bucket de Cloud Storage o a través del catálogo de tiempo de ejecución de Lakehouse.
  • Aceleración de consultas en columnas: Almacena en caché y propaga tablas de Iceberg en la memoria del motor de columnas de AlloyDB para un procesamiento analítico en menos de un segundo.
  • Interfaz de SQL estándar: Usa la sintaxis conocida de PostgreSQL para consultar y analizar tablas de Iceberg.

Cómo funciona el acceso directo a Iceberg

El acceso directo a Iceberg usa la interfaz del método de acceso a tablas (TAM) de PostgreSQL (USING iceberg) y se integra en el planificador y el framework de ejecución del motor de columnas de AlloyDB.

Cuando consultas una tabla de Iceberg, AlloyDB opera en uno de los siguientes modos:

  • Análisis directo (para lecturas de transmisión): AlloyDB lee los metadatos y los archivos de datos más recientes directamente desde Cloud Storage. El motor de columnas procesa los datos de forma continua.
  • Aceleración del motor de columnas (para lecturas almacenadas en caché en la memoria): cuando completas una tabla de Iceberg en el motor de columnas de AlloyDB con la función google_columnar_engine_add(), la tabla se carga en el almacén de columnas en la memoria. Las consultas posteriores se leen desde la memoria del motor de columnas, lo que maximiza la capacidad de procesamiento de las consultas y minimiza la latencia.

Entrega de instantáneas y actualización de la caché

La instantánea de la tabla de Iceberg que consulta AlloyDB depende del modo de lectura:

  • Análisis directo: AlloyDB ejecuta consultas en la instantánea de Iceberg más reciente. Cuando se inicia una consulta, AlloyDB determina la instantánea de la tabla de Iceberg más reciente disponible y lee los datos de esa instantánea, incluso dentro de una transacción REPEATABLE READ o SERIALIZABLE. AlloyDB no admite la fijación de instantáneas ni las consultas de un momento determinado en las transacciones.

    Por ejemplo, cuando consultas una tabla con un análisis directo, cada sentencia de una transacción lee desde la instantánea disponible más reciente:

    BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SELECT * FROM customer_orders;
-- If an external process commits a new Iceberg snapshot:
SELECT * FROM customer_orders; -- Returns results from the new snapshot.
COMMIT;

  • Aceleración del motor de columnas: AlloyDB ejecuta consultas en la instantánea que se propaga en el motor de columnas. Si AlloyDB escribe datos nuevos en la tabla de Iceberg subyacente en Cloud Storage después de la propagación, es posible que las consultas devuelvan datos obsoletos. Para obtener datos actualizados después de las operaciones de DML en la tabla subyacente, actualiza la caché con la función google_columnar_engine_refresh().

Tipos de datos admitidos

Cuando defines una tabla de Iceberg en AlloyDB, los nombres de las columnas y los tipos de datos de tu declaración DDL deben coincidir con los tipos del esquema de Iceberg subyacente.

El acceso directo a Iceberg admite los siguientes tipos de datos de Apache Iceberg y sus tipos de AlloyDB correspondientes:

Tipo de datos de Apache Iceberg Tipo de datos de AlloyDB Descripción
boolean BOOLEAN Conversión vectorizada al formato empaquetado en bytes
int INT/INTEGER Número entero de 32 bits con signo
long BIGINT Número entero de 64 bits con firma.
float REAL/FLOAT4 Número de punto flotante de precisión simple de 32 bits
double DOUBLE PRECISION/FLOAT8 Número de punto flotante de doble precisión de 64 bits
decimal(P, S) NUMERIC(P, S)/DECIMAL(P, S) Valor numérico de punto fijo con precisión P y escala S
string TEXT/VARCHAR Valores de cadena UTF-8
date DATE Fecha del calendario (año, mes, día)
timestamp TIMESTAMP Marca de tiempo sin zona horaria
timestamptz TIMESTAMPTZ Marca de tiempo con zona horaria

Limitaciones

El acceso directo a Iceberg tiene las siguientes limitaciones:

  • Disponibilidad de la versión de PostgreSQL: AlloyDB admite el acceso directo a Iceberg en PostgreSQL 18 y versiones posteriores.
  • Permisos de usuario: Solo los usuarios de la base de datos con el rol alloydbsuperuser pueden crear tablas de Iceberg. Después de crear una tabla, puedes otorgar permisos de SELECT a otros usuarios para que consulten la tabla de Iceberg.
  • Operaciones de solo lectura: AlloyDB solo admite consultas SELECT (DQL) en tablas de Iceberg. No admite operaciones de escritura (INSERT, UPDATE, DELETE, TRUNCATE).
  • Versión de la especificación de Apache Iceberg: AlloyDB no admite archivos de eliminación de Iceberg v2 (eliminaciones posicionales y de igualdad) ni vectores de eliminación de Iceberg v3.
  • Compatibilidad con formatos de archivo: El acceso directo a Iceberg admite archivos de datos de Parquet y archivos de metadatos JSON y Avro. No admite archivos de datos ORC.
  • Control de versiones de instantáneas: Las consultas de análisis directo se ejecutan en la instantánea de la tabla de Iceberg más reciente, y las consultas aceleradas por columnas se ejecutan en la instantánea propagada. AlloyDB no admite consultas de un momento determinado.
  • Evolución del esquema: AlloyDB no admite operaciones ALTER TABLE en tablas de Iceberg. La tabla de Iceberg subyacente no debe haber pasado por una migración de esquema.
  • Compatibilidad con el catálogo de metadatos: El acceso directo a Iceberg admite rutas de acceso directas a bucket de Cloud Storage (gs://) y rutas de acceso al catálogo de tiempo de ejecución de Lakehouse (bl://). Para el catálogo de tiempo de ejecución de Lakehouse, AlloyDB solo admite el modo de credenciales de usuario final. No admite el modo de venta de credenciales ni otros catálogos de REST.
  • Buckets de pagos del solicitante: AlloyDB no admite buckets de Cloud Storage que usen pagos del solicitante.
  • Restricción de propagación completa: AlloyDB no admite la propagación parcial de columnas para las tablas de Iceberg. Las tablas deben caber en la memoria del motor en columnas o en el espacio de SSD.
  • Memoria del montón de población: Propagar una tabla de Iceberg que contiene grupos de filas de Parquet grandes puede exceder el límite de memoria del montón de población por trabajador, en especial en instancias con menos CPU virtuales. Para resolver este problema, consulta El montón de población del motor de columnas está lleno.

Antes de comenzar

Antes de crear y consultar tablas de Iceberg, asegúrate de completar lo siguiente:

  1. Crea un clúster de AlloyDB que ejecute PostgreSQL 18 o una versión posterior en Google Cloud. Para obtener más información, consulta Crea un clúster.
  2. Aloja una tabla de Apache Iceberg en Cloud Storage o registrada en el catálogo de tiempo de ejecución de Lakehouse:
    • Para las rutas de acceso de Cloud Storage, la estructura del directorio del bucket debe seguir el diseño estándar de Apache Iceberg que contiene los subdirectorios data/ y metadata/, incluidos los archivos JSON de metadatos y version-hint.text. Para obtener más información, consulta Crea un bucket.
    • Para el catálogo de tiempo de ejecución de Lakehouse, crea y registra tu catálogo de Iceberg en el modo de credenciales de usuario final. Para obtener más información, consulta Configura el extremo del catálogo de REST de Apache Iceberg.
  3. Configura las credenciales de la base de datos para un usuario con el rol alloydbsuperuser. Para obtener más información, consulta el rol del grupo alloydbsuperuser.

Roles obligatorios

Para permitir que AlloyDB lea los datos y metadatos de Iceberg, debes otorgar los roles de IAM necesarios a la cuenta de servicio del clúster de AlloyDB:

  • Acceso a Cloud Storage: Otorga el rol de Visualizador de objetos de almacenamiento (roles/storage.objectViewer) en el bucket de Cloud Storage que contiene tus datos y metadatos de Iceberg.
  • Acceso a BigLake (si usas el catálogo de tiempo de ejecución de Lakehouse): otorga el rol de visualizador de BigLake (roles/biglake.viewer) en el proyecto que aloja tu catálogo de BigLake.

Para encontrar la cuenta de servicio del clúster, ejecuta el comando gcloud beta alloydb clusters describe:

gcloud beta alloydb clusters describe CLUSTER_ID --region=REGION_ID

Reemplaza lo siguiente:

  • CLUSTER_ID: Es el ID del clúster de AlloyDB.
  • REGION_ID: Es la ubicación del clúster de AlloyDB. Por ejemplo, us-east1 Para obtener una lista completa de las regiones, consulta Ubicaciones de AlloyDB.

El resultado contiene un campo serviceAccountEmail, que es la cuenta de servicio de este clúster. En la consola de Google Cloud , puedes encontrar la cuenta de servicio en la página Descripción general del clúster.

Para otorgar el rol de visualizador de objetos de Storage con gcloud CLI, ejecuta lo siguiente:

gcloud storage buckets add-iam-policy-binding \
    gs://BUCKET_NAME \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectViewer"

Si usas el catálogo de tiempo de ejecución de Lakehouse, otorga el rol de visualizador de BigLake:

gcloud projects add-iam-policy-binding LAKEHOUSE_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/biglake.viewer"

Reemplaza lo siguiente:

  • BUCKET_NAME: Es el nombre de tu bucket de Cloud Storage.
  • LAKEHOUSE_PROJECT_ID: Es el ID del proyecto de Google Cloud en el que se aloja tu catálogo de tiempo de ejecución de Lakehouse.
  • SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio del clúster que encontraste en el campo serviceAccountEmail.

Configurar marcas de bases de datos

Para habilitar el motor de columnas y el acceso directo a Iceberg, puedes configurar marcas de base de datos en tu instancia de AlloyDB. Establece las siguientes marcas de base de datos en tu instancia:

Marca de base de datos Valor Descripción
google_columnar_engine.enabled on Habilita el motor de columnas de AlloyDB.
google_columnar_engine.enable_iceberg_reads on Habilita el acceso directo a Iceberg. Deberás reiniciar la instancia.
google_columnar_engine.memory_size_in_mb SIZE_IN_MB Asigna memoria al motor de columnas (opcional). Se recomienda si planeas propagar tablas de Iceberg en la memoria.

Para configurar estas marcas con gcloud CLI, ejecuta el comando gcloud alloydb instances update:

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_iceberg_reads=on

Reemplaza lo siguiente:

  • INSTANCE_ID: Es el ID de tu instancia de AlloyDB.
  • CLUSTER_ID: Es el ID de tu clúster de AlloyDB.
  • REGION_ID: Es el ID de la región de tu clúster de AlloyDB.

Crea una tabla de Iceberg en AlloyDB

Para exponer un conjunto de datos de Apache Iceberg en AlloyDB, conéctate como un usuario con privilegios de alloydbsuperuser. Luego, crea una tabla con el método de acceso a la tabla USING iceberg.

CREATE TABLE TABLE_NAME (
    COLUMN_NAME DATA_TYPE [, ...]
)
USING iceberg
WITH (
    uri = 'LOCATION_URI'
);

Reemplaza lo siguiente:

  • TABLE_NAME: Es el nombre de la tabla que se creará en AlloyDB.
  • COLUMN_NAME y DATA_TYPE: Son las definiciones de las columnas. Los nombres y tipos de columnas deben coincidir con el esquema de la tabla de Iceberg subyacente.
  • LOCATION_URI: la ubicación de los metadatos de la tabla de Iceberg. Especifica uno de los siguientes formatos:
    • Ruta de acceso directa de Cloud Storage: gs://BUCKET_NAME/PATH_TO_ICEBERG_TABLE
    • URI del catálogo de tiempo de ejecución de Lakehouse: bl://projects/PROJECT_ID/catalogs/CATALOG_NAME/databases/DATABASE_NAME/tables/TABLE_NAME

Ejemplos

En los siguientes ejemplos, se muestra cómo crear tablas de Iceberg en AlloyDB.

Crea una tabla a partir de una ruta de acceso de Cloud Storage

En el siguiente ejemplo, se crea una tabla llamada customer_orders respaldada por un conjunto de datos de Iceberg ubicado en un bucket de Cloud Storage:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'gs://my-iceberg-analytics-bucket/datasets/sales/customer_orders'
);

Crea una tabla a partir del catálogo de tiempo de ejecución de Lakehouse

En el siguiente ejemplo, se crea una tabla que hace referencia a una tabla de Iceberg administrada por el catálogo de tiempo de ejecución de Lakehouse:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'bl://projects/my-analytics-project/catalogs/sales_catalog/databases/retail_db/tables/customer_orders'
);

Consulta datos de Iceberg

Después de crear la tabla en AlloyDB, puedes consultarla con sentencias de SQL estándar SELECT con privilegios de alloydbsuperuser. De manera opcional, puedes otorgar permisos de lectura a un usuario sin privilegios de alloydbsuperuser con la sentencia GRANT. Por ejemplo: GRANT SELECT ON customer_orders TO normal_user.

Consulta los datos

En el siguiente ejemplo, se muestra cómo ejecutar una consulta:

SELECT
    customer_id,
    COUNT(order_id) AS total_orders,
    SUM(total_amount) AS total_spent
FROM customer_orders
WHERE is_completed = true
  AND order_date >= '2026-01-01'
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10;

Consulta datos de Iceberg junto con datos operativos

Puedes combinar datos operativos en tiempo real que residen en AlloyDB con datos históricos que residen en Iceberg:

SELECT
    c.customer_name,
    c.account_tier,
    COUNT(o.order_id) AS total_orders,
    SUM(o.total_amount) AS historical_spend
FROM customer_orders o
JOIN customers c ON o.customer_id = c.customer_id
WHERE o.is_completed = true
GROUP BY c.customer_name, c.account_tier
ORDER BY historical_spend DESC;

Importa datos a una tabla local

Para crear una copia independiente y con permisos de escritura de los datos de Iceberg en el almacenamiento local de AlloyDB, ejecuta CREATE TABLE ... AS SELECT, como se muestra en el siguiente ejemplo:

CREATE TABLE local_customer_orders AS
SELECT * FROM customer_orders
WHERE order_date >= '2026-01-01';

Acelera las consultas con el motor de columnas

Para las cargas de trabajo analíticas que requieren una latencia ultrabaja, puedes propagar la tabla de Iceberg directamente en la memoria del motor de columnas de AlloyDB.

Propaga la tabla de Iceberg en el almacén de columnas

Para propagar todas las columnas de una tabla de Iceberg en el motor de columnas de AlloyDB, usa la función google_columnar_engine_add(). Por ejemplo:

SELECT google_columnar_engine_add('customer_orders');

Para propagar solo las columnas específicas que usan tus consultas, pasa una lista de nombres de columnas separada por comas como segundo argumento. Por ejemplo:

SELECT google_columnar_engine_add('customer_orders', 'customer_id,order_status');

Para obtener más información, consulta Agrega columnas con funciones de SQL.

Actualiza los datos propagados

Si escribes instantáneas nuevas en el conjunto de datos de Iceberg subyacente, actualiza la tabla para volver a cargar los datos más recientes en el motor de columnas de modo que las consultas devuelvan resultados actualizados:

SELECT google_columnar_engine_refresh('customer_orders');

Quita una tabla del almacén de columnas

Para quitar una tabla de Iceberg del almacén en columnas y volver al análisis directo, haz lo siguiente:

SELECT google_columnar_engine_drop('customer_orders');

Supervisa y verifica la ejecución de consultas

Puedes supervisar cómo AlloyDB ejecuta consultas en tablas de Iceberg y verificar si las consultas usan el motor de columnas en memoria. Usa vistas del sistema para verificar el estado de llenado de la caché y usa EXPLAIN para inspeccionar los planes de ejecución de consultas.

Verifica el estado del almacenamiento en caché de columnas

Para verificar si una tabla de Iceberg se propaga en el motor de columnas, consulta la vista del sistema g_columnar_relations:

SELECT relation_name, status
FROM g_columnar_relations
WHERE relation_name = 'customer_orders';

Un valor de status de USABLE confirma que la tabla se almacena en caché en la memoria del motor de columnas.

Inspecciona los planes de ejecución de consultas con EXPLAIN

Para verificar si una consulta aprovecha el motor de columnas, usa la sentencia EXPLAIN:

EXPLAIN (ANALYZE, COSTS OFF)
SELECT SUM(total_amount)
FROM customer_orders
WHERE is_completed = true;

El resultado indica la ejecución en columnas a través de un nodo Custom Scan (ColumnarScan) en la tabla:

Custom Scan (ColumnarScan) on customer_orders
  Filter: (is_completed = true)

Soluciona problemas

En esta sección, se describe cómo resolver problemas habituales cuando configuras y consultas tablas de Iceberg en AlloyDB.

La marca google_columnar_engine.enable_iceberg_reads está inhabilitada

Causa: La marca de la base de datos para el acceso directo a Iceberg está inhabilitada.

Corrección recomendada: Configura las marcas de base de datos google_columnar_engine.enabled=on y google_columnar_engine.enable_iceberg_reads=on en tu instancia y reiníciala.

Se denegó el permiso para acceder a Cloud Storage

Causa: La cuenta de servicio del clúster de AlloyDB no tiene acceso de lectura al bucket de Cloud Storage.

Corrección recomendada: Otorga el rol roles/storage.objectViewer a la cuenta de servicio del clúster en el bucket.

Se denegó el permiso para acceder al catálogo de tiempo de ejecución de Lakehouse

Causa: La cuenta de servicio del clúster de AlloyDB no tiene acceso de lectura al catálogo de tiempo de ejecución de Lakehouse.

Corrección recomendada: Otorga el rol roles/biglake.viewer a la cuenta de servicio del clúster en el proyecto de Google Cloud que aloja el catálogo de tiempo de ejecución de Lakehouse.

Falla la propagación de columnas

Causa: El tamaño de la tabla de Iceberg supera la memoria disponible y el espacio de SSD en el motor de columnas.

Corrección recomendada: Aumenta la asignación de memoria al motor de columnas con la marca google_columnar_engine.memory_size_in_mb en tu instancia o aumenta el tamaño de la caché de almacenamiento del motor de columnas con la marca google_columnar_engine.storage_cache_size. Para obtener más información, consulta Configura la caché de almacenamiento para el motor de columnas.

El montón de propagación del motor de columnas está lleno

Mensaje de error:

ERROR: Columnar engine population heap is full during population. Set
google_columnar_engine.population_heap_size_in_mb to a bigger value.

Causa: La memoria necesaria para propagar un grupo de filas de Parquet grande supera el límite de montón de propagación por trabajador.

Corrección recomendada: Reduce la cantidad de trabajadores de población paralelos para que el proceso de población pueda usar un montón más grande. En la sesión de SQL en la que completas la tabla, establece la marca google_job_scheduler.max_parallel_workers_per_job en 0 antes de llamar a la función google_columnar_engine_add():

SET google_job_scheduler.max_parallel_workers_per_job = 0;
SELECT google_columnar_engine_add('TABLE_NAME');

Reemplaza TABLE_NAME por el nombre de la tabla de Iceberg en AlloyDB.

¿Qué sigue?