Buenas prácticas de los lagos de datos

La guía de primeros pasos le muestra cómo consultar Apache Iceberg, Delta Lake, Apache Hudi y Apache Paimon por primera vez. Una vez completada la configuración inicial, use esta página para elegir el patrón de acceso adecuado, optimizar el rendimiento de las consultas y depurar consultas sobre el lago de datos en producción.

Pasa la ruta de almacenamiento y las credenciales directamente cuando conozcas la ubicación y no necesites una definición persistente de la tabla.

SELECT count()
FROM icebergS3('https://my-bucket.s3.amazonaws.com/warehouse/my_table/')
WHERE event_date >= today() - 7

Utiliza la variante S3 para AWS S3 y GCS. Azure y el sistema de archivos local tienen variantes específicas (icebergAzure, icebergLocal y sus equivalentes para otros formatos). Consulta consultas directas para ver la lista completa.

Paimon proporciona funciones de tabla y motores de tabla experimentales.

Cree una tabla con un motor de tabla si va a consultar la misma ruta repetidamente. ClickHouse almacena la ruta y las credenciales en los metadatos de la tabla, por lo que puede consultar un nombre de tabla normal en lugar de reconstruir la llamada a la función cada vez.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')

SELECT count() FROM events WHERE event_date = today()

Los motores de tabla admiten las mismas capacidades de lectura que las funciones de tabla, incluidas la caché de datos y la caché de metadatos. Los datos nunca se duplican en ClickHouse. Un motor de tabla resulta útil cuando se comparte el acceso con un equipo o se ejecutan trabajos programados sobre la misma tabla.

Conecte ClickHouse una sola vez cuando las tablas estén registradas en un catálogo de datos. Todas las tablas del catálogo aparecerán automáticamente como tablas de ClickHouse, incluidas las que se añadan en el origen después de crear la conexión.

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = 'us-east-1',
    aws_access_key_id = '<key>',
    aws_secret_access_key = '<secret>'

SELECT count() FROM my_lake.`analytics.events`

Esta opción escala mejor que crear definiciones de tablas individuales cuando administras muchas tablas o varios catálogos. Consulta conexión a catálogos y las guías de catálogos.

Muchas integraciones requieren activar una flag de función antes del primer uso. Comprueba la versión de tu servicio si CREATE DATABASE falla con un error de permisos.

En las conexiones a catálogos, cada tipo de catálogo tiene su propia flag. Consulta Conexión a catálogos para obtener una visión general y la referencia de DataLakeCatalog para ver los detalles de configuración. La configuración específica de cada catálogo se encuentra en las guías de catálogos.

Para las operaciones de escritura, Iceberg requiere allow_insert_into_iceberg (25.7+, Beta desde 26.2). Consulta Escritura en lagos de datos. Delta Lake requiere allow_delta_lake_writes (25.9+). La matriz de compatibilidad indica qué flags se aplican a cada formato y operación.

Los números de versión de esta página coinciden con las versiones de lanzamiento de ClickHouse (Cloud y autogestionado). Compruebe la versión de su servicio antes de habilitar una configuración o función.

El rendimiento de las consultas en Lake depende de la cantidad de metadatos y de archivos Parquet que ClickHouse lee del almacenamiento de objetos. Como con cualquier tabla de ClickHouse, el rendimiento de las consultas mejora al filtrar por columnas de partición y seleccionar menos columnas.

Filtre por columnas de partición en WHERE. Iceberg y Delta Lake almacenan metadatos de partición que permiten a ClickHouse omitir archivos irrelevantes durante la planificación de la consulta. Si el filtro apunta a una columna fuera de la especificación de partición, ClickHouse examina todos los archivos coincidentes.

Para tablas Iceberg con particionamiento oculto, filtre por la columna de origen en el esquema de la tabla, no por una columna de partición independiente ni por un nombre de campo transformado. Si la tabla está particionada por day(event_time), añada un predicado sobre event_time. ClickHouse obtiene la poda de particiones a partir de ese filtro mediante la especificación de partición de Iceberg. Consulte Poda de particiones y la especificación de Iceberg.

SELECT count()
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
  AND event_time < '2026-03-02'

Indica solo las columnas que necesitas en lugar de SELECT *. ClickHouse lee Parquet columna por columna desde el almacenamiento de objetos, por lo que las consultas SELECT más específicas reducen los bytes transferidos y descomprimidos.

Coloca los filtros selectivos en WHERE. A partir de ClickHouse 26.2+, PREWHERE también es compatible con las lecturas de tablas Iceberg y otras tablas de lago de datos, donde filtra en la capa Parquet antes de leer las columnas restantes. La poda de particiones sigue dependiendo del filtrado de las columnas de origen de la partición, no solo de PREWHERE.

Las tablas Iceberg con muchas position or equality deletes aplican filtrado merge-on-read durante los escaneos. Espera más trabajo por archivo de lo que sugiere por sí sola la poda de manifiestos.

En despliegues multinodo, usa cluster table functions para distribuir las lecturas de archivos entre réplicas.

En ClickHouse Cloud y en los servicios multinodo autogestionados, las variantes para clúster de las funciones de tabla de lago de datos distribuyen las lecturas de archivos Parquet entre las réplicas. El nodo iniciador reparte los archivos entre los workers en paralelo. Use las variantes para clúster para lecturas por lotes y cargas programadas sobre tablas grandes. En implementaciones de un solo nodo, la función de tabla estándar es suficiente.

Pase el nombre de su clúster como primer argumento ('default' en ClickHouse Cloud). Existen variantes para clúster para todos los formatos compatibles:

Puede combinar las lecturas en clúster con otros ajustes de rendimiento.

Para cargas por lotes repetidas desde tablas de lago de datos, limite cada ejecución a un rango de instantáneas en lugar de volver a leer la tabla completa. Sin estos límites, ClickHouse puede examinar todas las versiones y archivos en cada ejecución, lo que aumenta las lecturas desde el almacenamiento de objetos y el tiempo de consulta.

Guarde el identificador de la instantánea de la última carga completada correctamente y úselo como límite inferior en la siguiente ejecución.

• Para Iceberg, lea una vista en un momento concreto con iceberg_snapshot_id o iceberg_timestamp_ms (25.4+). En tablas de solo anexado, combine la configuración de instantáneas con filtros de partición en WHERE. Use system.iceberg_history (25.6+) para buscar IDs de instantánea entre ejecuciones.
• Para Delta Lake, lea los cambios entre dos versiones con delta_lake_snapshot_start_version y delta_lake_snapshot_end_version (25.12+). Lea una sola instantánea con delta_lake_snapshot_version (25.8+). Consulte flujo de cambios de datos de Delta para ver un ejemplo de CDF.

Ambos formatos respetan enable_filesystem_cache para mantener en el disco local los archivos Parquet de uso frecuente entre consultas. En implementaciones autogestionadas, configure un disco de caché del sistema de archivos en la configuración del servidor para que este ajuste tenga almacenamiento donde escribir. ClickHouse Cloud gestiona el almacenamiento en caché automáticamente. Establezca enable_filesystem_cache = 0 al realizar benchmarking para que los aciertos de la caché no oculten los cambios entre ejecuciones.

La mayoría de las optimizaciones de lectura de Iceberg están habilitadas de forma predeterminada. Los siguientes ajustes controlan la poda de particiones, la caché de metadatos y las idas y vueltas al catálogo.

Las tablas Iceberg conectadas a un catálogo obtienen metadatos en cada consulta, a menos que los almacenes en caché. Combina estas dos configuraciones (26.4+):

1. Define iceberg_metadata_async_prefetch_period_ms al crear la tabla para precargar metadatos en segundo plano.
2. Define iceberg_metadata_staleness_ms (26.3+) en las consultas para aceptar metadatos ligeramente desactualizados a cambio de evitar la ida y vuelta al catálogo.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')
SETTINGS iceberg_metadata_async_prefetch_period_ms = 60000;

SELECT count()
FROM events
SETTINGS iceberg_metadata_staleness_ms = 60000;

Un valor de obsolescencia de 0 siempre recupera los metadatos más recientes. Aumente la ventana en cargas de trabajo con muchas lecturas, donde las tablas cambian con poca frecuencia.

Cuando ClickHouse elige el archivo de metadatos incorrecto (varios archivos .metadata.json en la ruta de la tabla), fije la resolución con iceberg_metadata_file_path (25.4+) o iceberg_metadata_table_uuid durante la creación de la tabla. Consulte Resolución del archivo de metadatos.

Lea una instantánea histórica con iceberg_timestamp_ms o iceberg_snapshot_id (ambos en la versión 25.4+). No establezca ambos en la misma consulta. Inspeccione el linaje de las instantáneas en system.iceberg_history (25.6+) antes de elegir un ID. Para cargas por lotes repetidas, consulte Limitar las lecturas por lotes a instantáneas.

SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000

Además de allow_insert_into_iceberg (25.7+, Beta desde 26.2), puede controlar el tamaño del archivo de salida y el número de particiones durante la inserción:

Consulte Escritura en lagos de datos y la referencia del motor Iceberg.

Desde la versión 25.6, ClickHouse lee Delta Lake en S3 y GCS mediante el kernel de Rust de Delta Lake. La configuración se denomina allow_delta_kernel_rs en la versión 26.8 y posteriores, y allow_experimental_delta_kernel_rs en las versiones 25.5 a 26.7. En Azure Blob Storage, use deltaLakeAzure() con el lector heredado, ya que allí el kernel está deshabilitado. Sin el kernel, no están disponibles la poda de particiones, el flujo de cambios de datos ni la lectura de versiones de instantáneas.

La configuración de Delta Kernel debe estar habilitada para la poda de particiones, el flujo de cambios de datos y la lectura de versiones de instantáneas. Está activada de forma predeterminada en S3 y GCS a partir de la versión 25.5. Al habilitarla explícitamente, use el nombre correspondiente a su versión de ClickHouse.

Para la versión 26.8 y posteriores:

SET allow_delta_kernel_rs = 1;

Para las versiones 25.5 a 26.7:

SET allow_experimental_delta_kernel_rs = 1;

Las tablas con deletion vectors (26.2+) aplican filtrado a nivel de fila durante la lectura. ClickHouse gestiona esto automáticamente, pero los escaneos en tablas con muchas DV requieren más trabajo por archivo.

Para leer solo las filas que cambiaron entre dos instantáneas de Delta, establezca delta_lake_snapshot_start_version y delta_lake_snapshot_end_version (25.12+). La tabla debe tener activada en origen el flujo de cambios de datos (delta.enableChangeDataFeed). Establezca tanto la versión inicial como la versión final en los ajustes de consulta. Establecer solo la versión final produce un error.

SELECT *
FROM deltaLake('s3://my-bucket/warehouse/ga4_events/')
SETTINGS
    delta_lake_snapshot_start_version = 42,
    delta_lake_snapshot_end_version = 47

Almacene la versión final después de cada carga exitosa y pásela como versión inicial en la siguiente ejecución. El resultado incluye columnas de CDF (_change_type, _commit_version, _commit_timestamp). Procese estas columnas antes de cargarlas en su tabla de destino. Para el patrón general de instantáneas, consulte Acotar las lecturas por lotes a instantáneas.

Además de allow_delta_lake_writes (25.9+), controle el tamaño del archivo de salida al insertar:

SET allow_delta_lake_writes = 1;

INSERT INTO my_delta_table
SETTINGS
    delta_lake_insert_max_rows_in_data_file = 1000000,
    delta_lake_insert_max_bytes_in_data_file = 134217728
SELECT * FROM source_table

Las operaciones de escritura requieren Delta Kernel en S3 o GCS. Consulta la referencia del motor DeltaLake para ver ejemplos.

Las consultas del data lake que son lentas o devuelven resultados inesperados suelen deberse a lecturas de metadatos, poda de particiones o problemas de conectividad con el catálogo. Empiece por las comprobaciones siguientes y, si es necesario, use registros de metadatos específicos del formato.

CREATE DATABASE con DataLakeCatalog no valida las credenciales. Una base de datos puede existir aunque la conexión con el catálogo esté interrumpida. A partir de ClickHouse 26.4, ejecute una comprobación de estado ligera:

CHECK DATABASE my_lake;

En versiones anteriores, confirma la conectividad con SHOW TABLES FROM my_lake e inspecciona el mensaje de error. Usa SHOW CREATE TABLE con un nombre de tabla entre comillas invertidas para verificar la ruta de almacenamiento resuelta y el tipo de motor:

SHOW CREATE TABLE my_lake.`db.table`;

Si las tablas del catálogo no aparecen en system.tables, habilite show_remote_databases_in_system_tables (25.8+). De forma predeterminada, las tablas del catálogo están ocultas para la introspección del sistema. En las versiones anteriores a 26.6, use su nombre anterior, show_data_lake_catalogs_in_system_tables.

Iceberg y Delta Lake exponen columnas virtuales (_path, _file, _size, _time, _etag) en cada lectura. Agrupa por _path para comprobar si la poda de particiones está funcionando o si una consulta está analizando más archivos de los esperados. En las tablas Iceberg con particionamiento oculto, filtra por la columna de origen (por ejemplo, event_time), no por una columna de partición independiente:

SELECT _path, count() AS rows
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
  AND event_time < '2026-03-02'
GROUP BY _path
ORDER BY rows DESC;

Compare read_rows y read_bytes en system.query_log antes y después de añadir filtros o ajustar la configuración. ProfileEvents como ReadBufferFromS3Bytes y CachedReadBufferReadFromCacheBytes muestran cuántos datos provinieron del almacenamiento de objetos frente a la caché local. Consulte Diagnosticar consultas lentas para obtener una guía completa sobre query_log y EXPLAIN.

Desactive enable_filesystem_cache durante el benchmarking para que los aciertos de la caché no oculten los cambios entre ejecuciones.

ClickHouse expone tres tablas del sistema para depurar a nivel de metadatos. Habilite el registro solo al ejecutar la consulta. No están pensadas para la monitorización continua.

Ejecute una consulta con el registro habilitado, vacíe el registro y luego inspeccione las entradas de ese query_id:

SELECT count() FROM my_iceberg_table
SETTINGS iceberg_metadata_log_level = 'manifest_file_entry';

SYSTEM FLUSH LOGS iceberg_metadata_log;

SELECT content_type, file_path, pruning_status
FROM system.iceberg_metadata_log
WHERE query_id = '<previous_query_id>';

En ClickHouse Cloud, los datos de registro son locales a cada nodo. Usa clusterAllReplicas para ver el panorama completo en todas las réplicas.

Los niveles de log detallados de Iceberg deshabilitan la caché de metadatos para las manifest lists y los archivos, lo que ralentiza las consultas posteriores sobre la misma tabla. Usa una verbosidad alta solo mientras investigas activamente. Para problemas de predicados en Delta Lake, habilita delta_lake_throw_on_engine_predicate_error (25.8+) para fallar de inmediato cuando el kernel no pueda aplicar un filtro en el origen.

Consulta las páginas de referencia de iceberg_metadata_log y delta_lake_metadata_log para ver los detalles de las columnas y las opciones de verbosidad.

• Primeros pasos — Guía completa, desde las consultas directas hasta la escritura de datos
• Consultas directas — Funciones de tabla, motores y variantes de clúster para los cuatro formatos
• Conexión a catálogos — Configuración de DataLakeCatalog con Unity Catalog
• Escritura en lagos de datos — Escritura de datos en Iceberg y Delta Lake
• Matriz de compatibilidad — Comparación de funcionalidades entre formatos, catálogos y backends de almacenamiento