'
SELECT count() FROM my_lake.`analytics.events`
```
Essa abordagem escala melhor do que criar definições individuais de tabelas quando você gerencia muitas tabelas ou vários catálogos. Veja [Conectando-se a catálogos](/docs/use-cases/data-lake/getting-started/connecting-catalogs) e os [guias de catálogos](/docs/use-cases/data-lake/reference).
**Backticks para nomes de tabela com múltiplas partes**
Os catálogos costumam usar a nomenclatura `database.table`. Coloque o nome qualificado pelo banco de dados entre backticks, como no exemplo acima.
## Configurações necessárias
Muitas integrações exigem uma flag de recurso antes do primeiro uso. Verifique a versão do seu serviço se `CREATE DATABASE` falhar com um erro de permissão.
Para conexões com catálogos, cada tipo de catálogo tem sua própria flag. Consulte [Conectando-se a catálogos](/docs/use-cases/data-lake/getting-started/connecting-catalogs) para uma visão geral e a [referência do DataLakeCatalog](/docs/engines/database-engines/datalakecatalog) para detalhes das configurações. As instruções de setup de cada catálogo estão nos [guias de catálogo](/docs/use-cases/data-lake/reference).
Para gravação, o Iceberg exige [allow\_insert\_into\_iceberg](/docs/operations/settings/settings#allow_insert_into_iceberg) (25.7+, Beta a partir da 26.2). Consulte [Gravando em lagos de dados](/docs/use-cases/data-lake/getting-started/writing-data). O Delta Lake exige [allow\_delta\_lake\_writes](/docs/operations/settings/settings#allow_experimental_delta_lake_writes) (25.9+). A [matriz de suporte](/docs/use-cases/data-lake/support-matrix) lista quais flags se aplicam a cada formato e operação.
## Melhore o desempenho das consultas
Os números de versão nesta página correspondem às versões de lançamento do ClickHouse (Cloud e autogerenciado). Verifique a versão do seu serviço antes de ativar uma configuração ou funcionalidade.
O desempenho das consultas no Lake depende da quantidade de metadados e de quantos arquivos [Parquet](/docs/interfaces/formats/Parquet) o ClickHouse lê do armazenamento de objetos. Como em qualquer tabela do ClickHouse, o desempenho das consultas melhora ao filtrar pelas colunas de partição e selecionar menos colunas.
### Práticas de consulta
Aplique filtros às colunas de partição em `WHERE`. O Iceberg e o Delta Lake armazenam metadados de partição que permitem ao ClickHouse ignorar arquivos irrelevantes durante o planejamento da consulta. Se o filtro tiver como alvo uma coluna fora da especificação de partição, o ClickHouse examinará todos os arquivos correspondentes.
Para tabelas Iceberg com [particionamento oculto](https://iceberg.apache.org/docs/latest/partitioning/), aplique o filtro à **coluna de origem** no esquema da tabela — não a uma coluna de partição separada nem a um nome de campo transformado. Se a tabela for particionada por `day(event_time)`, adicione um predicado a `event_time`. O ClickHouse deriva a poda de partições desse filtro usando a especificação de partição do Iceberg. Consulte [Poda de partições](/docs/engines/table-engines/integrations/iceberg#partition-pruning) e a [especificação do 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'
```
Liste apenas as colunas de que você precisa em vez de `SELECT *`. O ClickHouse lê [Parquet](/docs/interfaces/formats/Parquet) coluna por coluna a partir do armazenamento de objetos, portanto consultas SELECT mais enxutas reduzem os bytes transferidos e descomprimidos.
Coloque filtros seletivos em `WHERE`. A partir do ClickHouse 26.2+, [PREWHERE](/docs/optimize/prewhere) também é compatível com leituras de tabelas Iceberg e outras tabelas de data lake, filtrando na camada Parquet antes de ler as colunas restantes. A poda de partições ainda depende da filtragem das colunas de origem da partição, não apenas do PREWHERE.
Tabelas Iceberg com muitas [exclusões por posição ou por igualdade](/docs/engines/table-engines/integrations/iceberg#deleted-rows) aplicam filtragem merge-on-read durante as varreduras. Espere mais trabalho por arquivo do que a simples poda de manifestos sugere.
Em implantações com vários nós, use [funções de tabela cluster](#parallel-cluster-reads) para distribuir leituras de arquivos entre réplicas.
### Leituras em paralelo em clusters com vários nós
No ClickHouse Cloud e em serviços autogerenciados com vários nós, as variantes de cluster das funções de tabela para data lakes distribuem as leituras de arquivos [Parquet](/docs/interfaces/formats/Parquet) entre as réplicas. O nó iniciador encaminha os arquivos para os workers em paralelo. Use variantes de cluster para leituras em lote e carregamentos agendados em tabelas grandes. Em implantações com um único nó, a função de tabela padrão é suficiente.
Passe o nome do seu cluster como primeiro argumento (`'default'` no ClickHouse Cloud). Há variantes de cluster para todos os formatos compatíveis:
| Formato | Funções de cluster |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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) |
Você pode combinar leituras em cluster com outras configurações de desempenho.
### Limite as leituras em lote a snapshots
Para cargas em lote recorrentes de tabelas de data lake, restrinja cada execução a um intervalo de snapshots em vez de reler a tabela inteira. Sem esses limites, o ClickHouse pode varrer todas as versões e arquivos em cada execução, o que aumenta as leituras no armazenamento de objetos e o tempo de consulta.
Armazene o identificador do snapshot da sua última carga bem-sucedida e use-o como limite inferior na execução seguinte.
* Para Iceberg, leia uma visão em um ponto no tempo com [iceberg\_snapshot\_id](/docs/operations/settings/settings#iceberg_snapshot_id) ou [iceberg\_timestamp\_ms](/docs/operations/settings/settings#iceberg_timestamp_ms) (25.4+). Para tabelas somente de acréscimo, combine as configurações de snapshot com filtros de partição em `WHERE`. Use [system.iceberg\_history](/docs/operations/system-tables/iceberg_history) (25.6+) para localizar IDs de snapshot entre execuções.
* Para Delta Lake, leia as alterações entre duas versões com [delta\_lake\_snapshot\_start\_version](/docs/operations/settings/settings#delta_lake_snapshot_start_version) e [delta\_lake\_snapshot\_end\_version](/docs/operations/settings/settings#delta_lake_snapshot_end_version) (25.12+). Leia um único snapshot com [delta\_lake\_snapshot\_version](/docs/operations/settings/settings#delta_lake_snapshot_version) (25.8+). Consulte [Delta change data feed](#delta-incremental-sync) para ver um exemplo de CDF.
### Armazene arquivos Parquet em cache localmente
Ambos os formatos aceitam [enable\_filesystem\_cache](/docs/operations/settings/settings#enable_filesystem_cache) para manter arquivos [Parquet](/docs/interfaces/formats/Parquet) mais acessados no disco local entre consultas. Em implantações autogerenciadas, configure um [disco de cache do sistema de arquivos](/docs/operations/storing-data#using-local-cache) na configuração do servidor para que essa configuração tenha onde gravar. O ClickHouse Cloud gerencia o cache automaticamente. Defina `enable_filesystem_cache = 0` ao fazer benchmarking para que os acessos ao cache não mascarem as mudanças entre execuções.
### Apache Iceberg
A maioria das otimizações de leitura do Apache Iceberg já vem habilitada por padrão. As configurações abaixo controlam a poda de partições, o cache de metadados e os round trips ao catálogo.
#### Configurações de leitura
| Configuração | Desde | Padrão | Observações |
| ------------------------------------------------------------------------------------------------------ | ----- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [use\_iceberg\_partition\_pruning](/docs/operations/settings/settings#use_iceberg_partition_pruning) | 25.1 | `1` a partir da 25.6 | Ignora arquivos de dados usando metadados de partição nos manifests |
| [use\_iceberg\_metadata\_files\_cache](/docs/operations/settings/settings#use_iceberg_metadata_files_cache) | 25.4 | `1` | Armazena em cache, na memória, listas de manifests e JSON de metadados |
| [iceberg\_metadata\_staleness\_ms](/docs/operations/settings/settings#iceberg_metadata_staleness_ms) | 26.3 | `0` | Configuração de consulta. Usa metadados em cache quando estiverem mais recentes do que esta janela, em vez de consultar o catálogo a cada consulta |
| [iceberg\_use\_version\_hint](/docs/sql-reference/table-functions/iceberg#writes-into-iceberg-table) | 25.6 | — | Lê `version-hint.text` para uma resolução de metadados mais rápida no acesso direto por caminho |
#### Reduza a latência do catálogo
Tabelas Iceberg conectadas ao catálogo fazem uma busca de metadados a cada consulta, a menos que você os coloque em cache. Combine duas configurações (26.4+):
1. Defina [iceberg\_metadata\_async\_prefetch\_period\_ms](/docs/engines/table-engines/integrations/iceberg#async-metadata-prefetch) ao criar a tabela para buscar metadados antecipadamente em segundo plano.
2. Defina [iceberg\_metadata\_staleness\_ms](/docs/operations/settings/settings#iceberg_metadata_staleness_ms) (26.3+) nas consultas para aceitar metadados ligeiramente desatualizados e, assim, evitar a ida e volta ao 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;
```
Um valor de staleness de `0` sempre busca os metadados mais recentes. Aumente a janela para workloads com muitas leituras, em que as tabelas mudam com pouca frequência.
Quando o ClickHouse seleciona o arquivo de metadados errado (vários arquivos `.metadata.json` no path da tabela), fixe a resolução com [iceberg\_metadata\_file\_path](/docs/engines/table-engines/integrations/iceberg#metadata-file-resolution) (25.4+) ou [iceberg\_metadata\_table\_uuid](/docs/engines/table-engines/integrations/iceberg#metadata-file-resolution) na criação da tabela. Consulte [Resolução do arquivo de metadados](/docs/engines/table-engines/integrations/iceberg#metadata-file-resolution).
#### Viagem no tempo
Leia um snapshot histórico com [iceberg\_timestamp\_ms](/docs/operations/settings/settings#iceberg_timestamp_ms) ou [iceberg\_snapshot\_id](/docs/operations/settings/settings#iceberg_snapshot_id) (ambos 25.4+). Não use os dois na mesma consulta. Inspecione a linhagem dos snapshots em [system.iceberg\_history](/docs/operations/system-tables/iceberg_history) (25.6+) antes de escolher um ID. Para cargas em lote repetidas, consulte [Limitar leituras em lote a snapshots](#snapshot-bounds).
```sql theme={null}
SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000
```
#### Gravações no Iceberg
Além de [allow\_insert\_into\_iceberg](/docs/operations/settings/settings#allow_insert_into_iceberg) (25.7+, Beta a partir da 26.2), controle o tamanho do arquivo de saída e o número de partições na inserção:
| Configuração | Desde | Finalidade |
| ------------------------------------------------------------------------------------------------------------------ | ----- | -------------------------------------------------- |
| [iceberg\_insert\_max\_rows\_in\_data\_file](/docs/operations/settings/settings#iceberg_insert_max_rows_in_data_file) | 25.9 | Limite de linhas por arquivo de dados de saída |
| [iceberg\_insert\_max\_bytes\_in\_data\_file](/docs/operations/settings/settings#iceberg_insert_max_bytes_in_data_file) | 25.9 | Limite de bytes por arquivo de dados de saída |
| [iceberg\_insert\_max\_partitions](/docs/operations/settings/settings#iceberg_insert_max_partitions) | 25.12 | Limite de partições gravadas em uma única inserção |
Consulte [Gravação em lagos de dados](/docs/use-cases/data-lake/getting-started/writing-data) e a [referência do motor Iceberg](/docs/engines/table-engines/integrations/iceberg).
### Delta Lake
A partir da versão 25.6, o ClickHouse lê Delta Lake no S3 e no GCS por meio do kernel do Delta Lake em Rust ([allow\_experimental\_delta\_kernel\_rs](/docs/operations/settings/settings#allow_experimental_delta_kernel_rs), 25.5+). No Azure Blob Storage, use [deltaLakeAzure()](/docs/sql-reference/table-functions/deltalake) com o leitor legado, porque o kernel fica desabilitado nesse ambiente. Sem o kernel, a poda de partições, o change data feed e a leitura de versões de snapshot não estão disponíveis.
#### Delta Kernel
[allow\_experimental\_delta\_kernel\_rs](/docs/operations/settings/settings#allow_experimental_delta_kernel_rs) deve estar habilitado para poda de partições, change data feed e leitura de versões de snapshot. Ele vem habilitado por padrão no S3 e no GCS a partir da versão 25.5. Habilite-o explicitamente em versões mais antigas ou ao solucionar problemas:
```sql theme={null}
SET allow_experimental_delta_kernel_rs = 1;
```
#### Configurações de leitura
| Configuração | Desde | Padrão | Notas |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------------------------------------------------------------------------------------------- |
| [delta\_lake\_enable\_engine\_predicate](/docs/operations/settings/settings#delta_lake_enable_engine_predicate) | 25.8 | `1` | Encaminha filtros ao kernel para poda de partições. Requer [Delta Kernel](#delta-kernel) |
| [delta\_lake\_reload\_schema\_for\_consistency](/docs/operations/settings/settings#delta_lake_reload_schema_for_consistency) | 26.3 | `0` | Recarrega o esquema antes de cada consulta quando gravadores concorrentes alteram o 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` | Lê alterações de CDF entre duas versões de snapshot. Requer CDF habilitado na origem |
| [delta\_lake\_snapshot\_version](/docs/operations/settings/settings#delta_lake_snapshot_version) | 25.8 | `-1` | Lê um único snapshot histórico. Defina `-1` para o mais recente (`0` é válido) |
Tabelas com [deletion vectors](https://docs.delta.io/latest/delta-deletion-vectors.html) (26.2+) aplicam filtragem em nível de linha durante a leitura. O ClickHouse lida com isso automaticamente, mas varreduras em tabelas com muitos DVs exigem mais trabalho por arquivo.
#### Feed de dados de alterações do Delta
Para ler apenas as linhas alteradas entre dois snapshots do Delta, defina [delta\_lake\_snapshot\_start\_version](/docs/operations/settings/settings#delta_lake_snapshot_start_version) e [delta\_lake\_snapshot\_end\_version](/docs/operations/settings/settings#delta_lake_snapshot_end_version) (25.12+). A tabela deve ter o change data feed habilitado na origem (`delta.enableChangeDataFeed`). Defina as versões inicial e final nas configurações da consulta. Definir apenas a versão final gera um erro.
```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
```
Armazene a versão final após cada carga bem-sucedida e passe-a como versão inicial na execução seguinte. O resultado inclui colunas do CDF (`_change_type`, `_commit_version`, `_commit_timestamp`). Trate essas colunas antes de carregá-las na sua tabela de destino. Para o padrão geral de snapshot, consulte [Restrinja leituras em lote a snapshots](#snapshot-bounds).
#### Gravações no Delta Lake
Além de [allow\_delta\_lake\_writes](/docs/operations/settings/settings#allow_experimental_delta_lake_writes) (25.9+), controle o tamanho do arquivo de saída no insert:
| Configuração | Desde | Finalidade |
| ------------------------------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------- |
| [delta\_lake\_insert\_max\_rows\_in\_data\_file](/docs/operations/settings/settings#delta_lake_insert_max_rows_in_data_file) | 25.9 | Limite de linhas por arquivo de dados de saída |
| [delta\_lake\_insert\_max\_bytes\_in\_data\_file](/docs/operations/settings/settings#delta_lake_insert_max_bytes_in_data_file) | 25.9 | Limite de bytes por arquivo de dados de saída |
```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
```
As gravações exigem o Delta Kernel no S3 ou no GCS. Consulte a [referência do motor DeltaLake](/docs/engines/table-engines/integrations/deltalake) para ver exemplos.
## Depurar consultas do data lake
Consultas no data lake que são lentas ou retornam resultados inesperados geralmente estão relacionadas a leituras de metadados, poda de partições ou conectividade com o catálogo. Comece pelas verificações abaixo e, depois, use logs de metadados específicos do formato, se necessário.
### Verifique a conectividade com o catálogo
`CREATE DATABASE` com `DataLakeCatalog` não valida as credenciais. Um banco de dados pode existir mesmo com a conexão com o catálogo indisponível. A partir do ClickHouse 26.4, execute um health check leve:
```sql theme={null}
CHECK DATABASE my_lake;
```
Em versões anteriores, confirme a conectividade com `SHOW TABLES FROM my_lake` e verifique a mensagem de erro. Use `SHOW CREATE TABLE` com o nome da tabela entre backticks para confirmar o caminho de armazenamento resolvido e o tipo de engine:
```sql theme={null}
SHOW CREATE TABLE my_lake.`db.table`;
```
Se as tabelas do catálogo não aparecerem em `system.tables`, habilite [show\_remote\_databases\_in\_system\_tables](/docs/operations/settings/settings#show_remote_databases_in_system_tables) (25.8+). Por padrão, as tabelas do catálogo ficam ocultas na introspecção do sistema. Em versões anteriores à 26.6, use o nome antigo, `show_data_lake_catalogs_in_system_tables`.
### Veja quais arquivos são lidos
Iceberg e Delta Lake expõem [colunas virtuais](/docs/sql-reference/table-functions/iceberg#virtual-columns) (`_path`, `_file`, `_size`, `_time`, `_etag`) a cada leitura. Agrupe por `_path` para verificar se a poda de partições está funcionando ou se uma consulta está varrendo mais arquivos do que o esperado. Para tabelas Iceberg com particionamento oculto, filtre pela coluna de origem (por exemplo, `event_time`), não por uma coluna de partição separada:
```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;
```
### Verifique o volume de leitura
Compare `read_rows` e `read_bytes` em [system.query\_log](/docs/operations/system-tables/query_log) antes e depois de adicionar filtros ou ajustar configurações. ProfileEvents como `ReadBufferFromS3Bytes` e `CachedReadBufferReadFromCacheBytes` mostram quanto dos dados veio do armazenamento de objetos em comparação com o cache local. Consulte [Otimização de consultas](/docs/optimize/query-optimization) para um passo a passo completo sobre o query\_log e o EXPLAIN.
Desative [enable\_filesystem\_cache](/docs/operations/settings/settings#enable_filesystem_cache) durante o benchmarking para que os acertos de cache não mascarem as mudanças entre execuções.
### Logs de metadados
O ClickHouse expõe três tabelas de sistema para depuração no nível de metadados. Habilite o logging apenas durante a consulta. Elas não se destinam a monitoramento contínuo.
| Tabela de sistema | Formato | Desde | Habilitar com | Use 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) na consulta | Rastrear arquivos de metadados lidos e decisões de poda de partições |
| [system.iceberg\_history](/docs/operations/system-tables/iceberg_history) | Iceberg | 25.6 | Preenchida automaticamente para tabelas Iceberg no ClickHouse | Inspecionar a linhagem dos snapshots antes de consultas com viagem no tempo |
| [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` na consulta | Rastrear arquivos de metadados do Delta e a resolução de snapshots |
Execute uma consulta com o logging habilitado, force o flush do log e, em seguida, inspecione as entradas desse `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 = '';
```
No ClickHouse Cloud, os dados de log são locais a cada nó. Use `clusterAllReplicas` para ver o panorama completo entre as réplicas.
Os níveis de log Verbose do Iceberg desativam o cache de metadados para listas de manifest e arquivos, o que torna mais lentas as consultas subsequentes na mesma tabela. Use alta verbosidade apenas enquanto estiver investigando ativamente. Para problemas de predicado no Delta Lake, habilite [delta\_lake\_throw\_on\_engine\_predicate\_error](/docs/operations/settings/settings#delta_lake_throw_on_engine_predicate_error) (25.8+) para falhar rapidamente quando o kernel não conseguir fazer pushdown de um filtro.
Consulte as páginas de referência de [iceberg\_metadata\_log](/docs/operations/system-tables/iceberg_metadata_log) e [delta\_lake\_metadata\_log](/docs/operations/system-tables/delta_lake_metadata_log) para ver detalhes das colunas e opções de verbosidade.
## Próximos passos
* [Primeiros passos](/docs/use-cases/data-lake/getting-started) — Guia completo, da consulta direta à gravação de dados de volta
* [Consultando diretamente](/docs/use-cases/data-lake/getting-started/querying-directly) — Funções de tabela, motores e variantes de cluster para os quatro formatos
* [Conectando-se a catálogos](/docs/use-cases/data-lake/getting-started/connecting-catalogs) — Configuração do `DataLakeCatalog` com Unity Catalog
* [Gravando em lagos de dados](/docs/use-cases/data-lake/getting-started/writing-data) — Grave dados de volta no Iceberg e no Delta Lake
* [Matriz de suporte](/docs/use-cases/data-lake/support-matrix) — Comparação de recursos entre formatos, catálogos e backends de armazenamento