'
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 [Conectarse a catálogos](/docs/use-cases/data-lake/getting-started/connecting-catalogs) y las [guías de catálogos](/docs/use-cases/data-lake/reference).
**Comillas invertidas en nombres de tabla de varias partes**
Los 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](/docs/use-cases/data-lake/getting-started/connecting-catalogs) para obtener una visión general y la [referencia de DataLakeCatalog](/docs/engines/database-engines/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](/docs/use-cases/data-lake/reference).
Para las operaciones de escritura, Iceberg requiere [allow\_insert\_into\_iceberg](/docs/operations/settings/settings#allow_insert_into_iceberg) (25.7+, Beta desde 26.2). Consulta [Escritura en lagos de datos](/docs/use-cases/data-lake/getting-started/writing-data). Delta Lake requiere [allow\_delta\_lake\_writes](/docs/operations/settings/settings#allow_experimental_delta_lake_writes) (25.9+). La [matriz de compatibilidad](/docs/use-cases/data-lake/support-matrix) 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](/docs/interfaces/formats/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](https://iceberg.apache.org/docs/latest/partitioning/), 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](/docs/engines/table-engines/integrations/iceberg#partition-pruning) y la [especificación de Iceberg](https://iceberg.apache.org/spec/#partitioning).
```sql theme={null}
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](/docs/interfaces/formats/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](/docs/optimize/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](/docs/engines/table-engines/integrations/iceberg#deleted-rows) 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](#parallel-cluster-reads) 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](/docs/interfaces/formats/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:
| Formato | Funciones de clúster |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Iceberg | [icebergS3Cluster()](/docs/sql-reference/table-functions/icebergCluster), [icebergAzureCluster()](/docs/sql-reference/table-functions/icebergCluster) |
| Delta Lake | [deltaLakeCluster()](/docs/sql-reference/table-functions/deltalakeCluster), [deltaLakeAzureCluster()](/docs/sql-reference/table-functions/deltalakeCluster) |
| Hudi | [hudiCluster()](/docs/sql-reference/table-functions/hudiCluster) |
| Paimon | [paimonS3Cluster()](/docs/sql-reference/table-functions/paimonCluster) |
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.
* Para Iceberg, lea una vista en un momento concreto con [iceberg\_snapshot\_id](/docs/operations/settings/settings#iceberg_snapshot_id) o [iceberg\_timestamp\_ms](/docs/operations/settings/settings#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](/docs/operations/system-tables/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](/docs/operations/settings/settings#delta_lake_snapshot_start_version) y [delta\_lake\_snapshot\_end\_version](/docs/operations/settings/settings#delta_lake_snapshot_end_version) (25.12+). Lea una sola instantánea con [delta\_lake\_snapshot\_version](/docs/operations/settings/settings#delta_lake_snapshot_version) (25.8+). Consulte [Delta change data feed](#delta-incremental-sync) para ver un ejemplo de CDF.
### Almacenar archivos Parquet en caché localmente
Ambos formatos respetan [enable\_filesystem\_cache](/docs/operations/settings/settings#enable_filesystem_cache) para mantener en el disco local los archivos [Parquet](/docs/interfaces/formats/Parquet) de uso frecuente entre consultas. En implementaciones autogestionadas, configure un [disco de caché del sistema de archivos](/docs/operations/storing-data#using-local-cache) 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
| Configuración | Desde | Predeterminado | Notas |
| ------------------------------------------------------------------------------------------------------ | ----- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [use\_iceberg\_partition\_pruning](/docs/operations/settings/settings#use_iceberg_partition_pruning) | 25.1 | `1` desde 25.6 | Omite archivos de datos mediante metadatos de partición en los manifiestos |
| [use\_iceberg\_metadata\_files\_cache](/docs/operations/settings/settings#use_iceberg_metadata_files_cache) | 25.4 | `1` | Almacena en caché en memoria las listas de manifiestos y el JSON de metadatos |
| [iceberg\_metadata\_staleness\_ms](/docs/operations/settings/settings#iceberg_metadata_staleness_ms) | 26.3 | `0` | Configuración de consulta. Usa metadatos en caché cuando son más recientes que esta ventana, en lugar de llamar al catálogo en cada consulta |
| [iceberg\_use\_version\_hint](/docs/sql-reference/table-functions/iceberg#writes-into-iceberg-table) | 25.6 | — | Lee `version-hint.text` para resolver los metadatos más rápido en el acceso directo mediante ruta |
#### Reduce la latencia del 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](/docs/engines/table-engines/integrations/iceberg#async-metadata-prefetch) al crear la tabla para precargar metadatos en segundo plano.
2. Define [iceberg\_metadata\_staleness\_ms](/docs/operations/settings/settings#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.
```sql theme={null}
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](/docs/engines/table-engines/integrations/iceberg#metadata-file-resolution) (25.4+) o [iceberg\_metadata\_table\_uuid](/docs/engines/table-engines/integrations/iceberg#metadata-file-resolution) durante la creación de la tabla. Consulte [Resolución del archivo de metadatos](/docs/engines/table-engines/integrations/iceberg#metadata-file-resolution).
#### Viaje temporal
Lea una instantánea histórica con [iceberg\_timestamp\_ms](/docs/operations/settings/settings#iceberg_timestamp_ms) o [iceberg\_snapshot\_id](/docs/operations/settings/settings#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](/docs/operations/system-tables/iceberg_history) (25.6+) antes de elegir un ID. Para cargas por lotes repetidas, consulte [Limitar las lecturas por lotes a instantáneas](#snapshot-bounds).
```sql theme={null}
SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000
```
#### Escrituras en Iceberg
Además de [allow\_insert\_into\_iceberg](/docs/operations/settings/settings#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:
| Configuración | Desde | Propósito |
| ------------------------------------------------------------------------------------------------------------------ | ----- | ---------------------------------------------------- |
| [iceberg\_insert\_max\_rows\_in\_data\_file](/docs/operations/settings/settings#iceberg_insert_max_rows_in_data_file) | 25.9 | Límite de filas por archivo de datos de salida |
| [iceberg\_insert\_max\_bytes\_in\_data\_file](/docs/operations/settings/settings#iceberg_insert_max_bytes_in_data_file) | 25.9 | Límite de bytes por archivo de datos de salida |
| [iceberg\_insert\_max\_partitions](/docs/operations/settings/settings#iceberg_insert_max_partitions) | 25.12 | Límite de particiones escritas en una sola inserción |
Consulte [Escritura en lagos de datos](/docs/use-cases/data-lake/getting-started/writing-data) y la [referencia del motor Iceberg](/docs/engines/table-engines/integrations/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](/docs/operations/settings/settings#allow_experimental_delta_kernel_rs), 25.5+). En Azure Blob Storage, use [deltaLakeAzure()](/docs/sql-reference/table-functions/deltalake) 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](/docs/operations/settings/settings#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:
```sql theme={null}
SET allow_experimental_delta_kernel_rs = 1;
```
#### Ajustes de lectura
| Ajuste | Desde | Predeterminado | Notas |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------- | ----------------------------------------------------------------------------------------------------- |
| [delta\_lake\_enable\_engine\_predicate](/docs/operations/settings/settings#delta_lake_enable_engine_predicate) | 25.8 | `1` | Pasa los filtros al kernel para la poda de particiones. Requiere [Delta Kernel](#delta-kernel) |
| [delta\_lake\_reload\_schema\_for\_consistency](/docs/operations/settings/settings#delta_lake_reload_schema_for_consistency) | 26.3 | `0` | Recarga el esquema antes de cada consulta cuando escritores concurrentes hacen evolucionar el esquema |
| [delta\_lake\_snapshot\_start\_version](/docs/operations/settings/settings#delta_lake_snapshot_start_version) / [delta\_lake\_snapshot\_end\_version](/docs/operations/settings/settings#delta_lake_snapshot_end_version) | 25.12 | `-1` | Lee cambios de CDF entre dos versiones de instantánea. Requiere que CDF esté habilitado en upstream |
| [delta\_lake\_snapshot\_version](/docs/operations/settings/settings#delta_lake_snapshot_version) | 25.8 | `-1` | Lee una única instantánea histórica. Establece `-1` para la más reciente (`0` es válido) |
Las tablas con [deletion vectors](https://docs.delta.io/latest/delta-deletion-vectors.html) (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](/docs/operations/settings/settings#delta_lake_snapshot_start_version) y [delta\_lake\_snapshot\_end\_version](/docs/operations/settings/settings#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.
```sql theme={null}
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](#snapshot-bounds).
#### Escrituras en Delta Lake
Además de [allow\_delta\_lake\_writes](/docs/operations/settings/settings#allow_experimental_delta_lake_writes) (25.9+), controle el tamaño del archivo de salida al insertar:
| Configuración | Desde | Propósito |
| ------------------------------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------- |
| [delta\_lake\_insert\_max\_rows\_in\_data\_file](/docs/operations/settings/settings#delta_lake_insert_max_rows_in_data_file) | 25.9 | Límite de filas por archivo de datos de salida |
| [delta\_lake\_insert\_max\_bytes\_in\_data\_file](/docs/operations/settings/settings#delta_lake_insert_max_bytes_in_data_file) | 25.9 | Límite de bytes por archivo de datos de salida |
```sql theme={null}
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](/docs/engines/table-engines/integrations/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.
### 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:
```sql theme={null}
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:
```sql theme={null}
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](/docs/operations/settings/settings#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](/docs/sql-reference/table-functions/iceberg#virtual-columns) (`_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:
```sql theme={null}
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;
```
### Comprobar el volumen de escaneo
Compare `read_rows` y `read_bytes` en [system.query\_log](/docs/operations/system-tables/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](/docs/optimize/query-optimization) para obtener una guía completa sobre query\_log y EXPLAIN.
Desactive [enable\_filesystem\_cache](/docs/operations/settings/settings#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.
| Tabla del sistema | Formato | Desde | Habilitar con | Úsela para |
| -------------------------------------------------------------------------------------- | ---------- | ----- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [system.iceberg\_metadata\_log](/docs/operations/system-tables/iceberg_metadata_log) | Iceberg | 25.9 | [iceberg\_metadata\_log\_level](/docs/operations/settings/settings#iceberg_metadata_log_level) en la consulta | Rastrear los archivos de metadatos leídos y las decisiones de poda de particiones |
| [system.iceberg\_history](/docs/operations/system-tables/iceberg_history) | Iceberg | 25.6 | Se pobla automáticamente para las tablas Iceberg de ClickHouse | Inspeccionar el linaje de snapshots antes de las consultas de viaje en el tiempo |
| [system.delta\_lake\_metadata\_log](/docs/operations/system-tables/delta_lake_metadata_log) | Delta Lake | 25.10 | [delta\_lake\_log\_metadata](/docs/operations/settings/settings#delta_lake_log_metadata) = `1` en la consulta | Rastrear los archivos de metadatos de Delta y la resolución de snapshots |
Ejecute una consulta con el registro habilitado, vacíe el registro y luego inspeccione las entradas de ese `query_id`:
```sql theme={null}
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 = '';
```
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](/docs/operations/settings/settings#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](/docs/operations/system-tables/iceberg_metadata_log) y [delta\_lake\_metadata\_log](/docs/operations/system-tables/delta_lake_metadata_log) para ver los detalles de las columnas y las opciones de verbosidad.
## Próximos pasos
* [Primeros pasos](/docs/use-cases/data-lake/getting-started) — Guía completa desde la consulta directa hasta la escritura en destino
* [Consulta directa](/docs/use-cases/data-lake/getting-started/querying-directly) — Funciones de tabla, motores y variantes de clúster para los cuatro formatos
* [Conectarse a catálogos](/docs/use-cases/data-lake/getting-started/connecting-catalogs) — Configuración de `DataLakeCatalog` con Unity Catalog
* [Escribir en lagos de datos](/docs/use-cases/data-lake/getting-started/writing-data) — Escritura de datos en Iceberg y Delta Lake
* [Matriz de compatibilidad](/docs/use-cases/data-lake/support-matrix) — Comparación de características entre formatos, catálogos y backends de almacenamiento