Skip to main content
O guia de primeiros passos mostra como consultar Apache Iceberg, Delta Lake, Apache Hudi e Apache Paimon pela primeira vez. Depois de concluir a configuração, use esta página para escolher o padrão de acesso adequado, otimizar o desempenho das consultas e depurar consultas ao lago de dados em produção.

Escolha um método de acesso

Funções de tabela

Passe o caminho de armazenamento e as credenciais inline quando souber o local e não precisar de uma definição de tabela persistente.
Use a variante S3 para AWS S3 e GCS. O Azure e o sistema de arquivos local têm variantes dedicadas (icebergAzure, icebergLocal e equivalentes para outros formatos). Consulte Consultar diretamente para ver a lista completa. Paimon oferece apenas funções de tabela.

Motores de tabela

Crie uma tabela com um motor de tabela quando for consultar o mesmo caminho repetidamente. O ClickHouse armazena o caminho e as credenciais nos metadados da tabela, para que você consulte um nome de tabela comum em vez de reconstruir a chamada da função todas as vezes.
Os motores de tabela suportam os mesmos recursos de leitura que as funções de tabela, incluindo cache de dados e cache de metadados. Os dados nunca são duplicados no ClickHouse. Um motor de tabela é útil quando você compartilha o acesso com a equipe ou executa jobs agendados na mesma tabela.

motor de banco de dados DataLakeCatalog

Conecte o ClickHouse uma única vez a um catálogo de dados externo no qual as tabelas estejam registradas. Cada tabela do catálogo aparece automaticamente como uma tabela do ClickHouse, inclusive as tabelas adicionadas posteriormente, depois que você criar a conexão.
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 e os guias de catálogos.
Backticks para nomes de tabela com múltiplas partesOs 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 para uma visão geral e a referência do DataLakeCatalog para detalhes das configurações. As instruções de setup de cada catálogo estão nos guias de catálogo. Para gravação, o Iceberg exige allow_insert_into_iceberg (25.7+, Beta a partir da 26.2). Consulte Gravando em lagos de dados. O Delta Lake exige allow_delta_lake_writes (25.9+). A matriz de suporte 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 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, 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 e a especificação do Iceberg.
Liste apenas as colunas de que você precisa em vez de SELECT *. O ClickHouse lê 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 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 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 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 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: 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.

Armazene arquivos Parquet em cache localmente

Ambos os formatos aceitam enable_filesystem_cache para manter arquivos Parquet mais acessados no disco local entre consultas. Em implantações autogerenciadas, configure um disco de cache do sistema de arquivos 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

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 ao criar a tabela para buscar metadados antecipadamente em segundo plano.
  2. Defina iceberg_metadata_staleness_ms (26.3+) nas consultas para aceitar metadados ligeiramente desatualizados e, assim, evitar a ida e volta ao catálogo.
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 (25.4+) ou iceberg_metadata_table_uuid na criação da tabela. Consulte Resolução do arquivo de metadados.

Viagem no tempo

Leia um snapshot histórico com iceberg_timestamp_ms ou iceberg_snapshot_id (ambos 25.4+). Não use os dois na mesma consulta. Inspecione a linhagem dos snapshots em system.iceberg_history (25.6+) antes de escolher um ID. Para cargas em lote repetidas, consulte Limitar leituras em lote a snapshots.

Gravações no Iceberg

Além de 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: Consulte Gravação em lagos de dados e a referência do motor 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, 25.5+). No Azure Blob Storage, use deltaLakeAzure() 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 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:

Configurações de leitura

Tabelas com deletion vectors (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 e 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.
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.

Gravações no Delta Lake

Além de allow_delta_lake_writes (25.9+), controle o tamanho do arquivo de saída no insert:
As gravações exigem o Delta Kernel no S3 ou no GCS. Consulte a referência do motor 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.
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:
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:
Se as tabelas do catálogo não aparecerem em system.tables, habilite 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 (_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:

Verifique o volume de leitura

Compare read_rows e read_bytes em system.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 para um passo a passo completo sobre o query_log e o EXPLAIN. Desative 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. Execute uma consulta com o logging habilitado, force o flush do log e, em seguida, inspecione as entradas desse 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 (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 e delta_lake_metadata_log para ver detalhes das colunas e opções de verbosidade.

Próximos passos

Última modificação em 23 de julho de 2026