Elija un método de acceso
Funciones de tabla
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
Motor de base de datos DataLakeCatalog
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
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
Hábitos de consulta
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 *. 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
'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 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 Delta change data feed para ver un ejemplo de CDF.
Almacenar archivos Parquet en caché localmente
enable_filesystem_cache = 0 al realizar benchmarking para que los aciertos de la caché no oculten los cambios entre ejecuciones.
Apache Iceberg
Configuración de lectura
Reduce la latencia del catálogo
- Define iceberg_metadata_async_prefetch_period_ms al crear la tabla para precargar metadatos en segundo plano.
- 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.
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
Escrituras en Iceberg
Consulte Escritura en lagos de datos y la referencia del motor Iceberg.
Delta Lake
Delta Kernel
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
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.
_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
Depurar consultas del data lake
Verificar la conectividad del catálogo
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:
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:
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
_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
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
Ejecute una consulta con el registro habilitado, vacíe el registro y luego inspeccione las entradas de ese
query_id:
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
- Primeros pasos — Guía completa desde la consulta directa hasta la escritura en destino
- Consulta directa — Funciones de tabla, motores y variantes de clúster para los cuatro formatos
- Conectarse a catálogos — Configuración de
DataLakeCatalogcon Unity Catalog - Escribir en lagos de datos — Escritura de datos en Iceberg y Delta Lake
- Matriz de compatibilidad — Comparación de características entre formatos, catálogos y backends de almacenamiento