Skip to main content
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.

Elija un método de acceso

Funciones de tabla

Pasa la ruta de almacenamiento y las credenciales directamente cuando conozcas la ubicación y no necesites una definición persistente de la tabla.
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 Consultar directamente para ver la lista completa. Paimon solo admite funciones de tabla.

Motores de tabla

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.
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.

Motor de base de datos DataLakeCatalog

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.
Esta opción escala mejor que crear definiciones de tablas individuales cuando administras muchas tablas o varios catálogos. Consulta Conectarse a catálogos y las guías de catálogos.
Comillas invertidas en nombres de tabla de varias partesLos catálogos suelen usar la nomenclatura database.table. Encierra entre comillas invertidas el nombre calificado con la base de datos, como en el ejemplo anterior.

Configuración requerida

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.

Mejorar el rendimiento de las consultas

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.

Hábitos de consulta

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.
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 data lake, 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.

Lecturas en paralelo en clústeres multinodo

En ClickHouse Cloud y en los servicios multinodo autogestionados, las variantes para clúster de las funciones de tabla de lake 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.

Limite las lecturas por lotes a instantáneas

Para cargas por lotes repetidas desde tablas de lago, 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.

Almacenar archivos Parquet en caché localmente

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.

Apache Iceberg

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.

Configuración de lectura

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.
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.

Viaje temporal

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.

Escrituras en Iceberg

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.

Delta Lake

Desde la versión 25.6, ClickHouse lee Delta Lake en S3 y GCS mediante el kernel de Rust de Delta Lake (allow_experimental_delta_kernel_rs, 25.5+). 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 change data feed ni la lectura de versiones de snapshots.

Delta Kernel

allow_experimental_delta_kernel_rs debe estar habilitado para la poda de particiones, el flujo de cambios de datos y la lectura de versiones de instantáneas. Está activado de forma predeterminada en S3 y GCS a partir de la versión 25.5. Habilítelo explícitamente en versiones anteriores o para la resolución de problemas:

Ajustes de lectura

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.

Fuente de cambios de datos de Delta

Para leer solo las filas que cambiaron entre dos snapshots de Delta, establezca delta_lake_snapshot_start_version y delta_lake_snapshot_end_version (25.12+). La tabla debe tener activada en origen la fuente 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.
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.

Escrituras en Delta Lake

Además de allow_delta_lake_writes (25.9+), controle el tamaño del archivo de salida al insertar:
Las operaciones de escritura requieren Delta Kernel en S3 o GCS. Consulta la referencia del motor DeltaLake para ver ejemplos.

Depurar consultas del data lake

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:
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:
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.

Ver qué archivos se leen

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:

Comprobar el volumen de escaneo

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 Optimización de consultas para obtener una guía completa sobre query_log y EXPLAIN. Desactive enable_filesystem_cache durante el benchmark para que los aciertos de la caché no oculten los cambios entre ejecuciones.

Registros de metadatos

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:
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.

Próximos pasos

Última modificación el 23 de julio de 2026