Boas práticas para lagos de dados

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.

Passe o caminho de armazenamento e as credenciais inline quando souber o local e não precisar de uma definição de tabela persistente.

SELECT count()
FROM icebergS3('https://my-bucket.s3.amazonaws.com/warehouse/my_table/')
WHERE event_date >= today() - 7

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 consulta direta para ver a lista completa.

Paimon oferece funções de tabela e motores de tabela experimentais.

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.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')

SELECT count() FROM events WHERE event_date = today()

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.

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.

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = 'us-east-1',
    aws_access_key_id = '<key>',
    aws_secret_access_key = '<secret>'

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 e os guias de catálogos.

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

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.

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.

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.

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

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.

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 ou 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 (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 e delta_lake_snapshot_end_version (25.12+). Leia um único snapshot com delta_lake_snapshot_version (25.8+). Consulte Feed de dados de alterações do Delta para ver um exemplo de CDF.

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 acertos de cache não mascarem as mudanças entre execuções.

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.

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.

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 (25.4+) ou iceberg_metadata_table_uuid na criação da tabela. Consulte Resolução do arquivo de metadados.

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 Limite as leituras em lote a snapshots.

SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000

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 Gravando em lagos de dados e a referência do motor Iceberg.

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. A configuração chama-se allow_delta_kernel_rs na versão 26.8 e posteriores, e allow_experimental_delta_kernel_rs nas versões 25.5 a 26.7. 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 Feed de dados de alterações e a leitura de versões de snapshot não estão disponíveis.

A configuração do Delta kernel deve estar habilitada para poda de partições, Feed de dados de alterações 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. Ao habilitá-la explicitamente, use o nome correspondente à sua versão do ClickHouse.

Para a versão 26.8 e posteriores:

SET allow_delta_kernel_rs = 1;

Para as versões de 25.5 a 26.7:

SET allow_experimental_delta_kernel_rs = 1;

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.

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.

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 Limite as leituras em lote a snapshots.

Além de allow_delta_lake_writes (25.9+), controle o tamanho do arquivo de saída no insert:

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 para ver exemplos.

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:

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:

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

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:

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;

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 Diagnostique consultas lentas 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.

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:

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 = '<previous_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.

• Primeiros passos — Guia completo, da consulta direta à gravação dos dados de volta
• Consultas diretas — Funções de tabela, motores e variantes de cluster para os quatro formatos
• Conectando-se a catálogos — Configuração do DataLakeCatalog com o Unity Catalog
• Gravando em lagos de dados — Grave dados de volta no Iceberg e no Delta Lake
• Matriz de suporte — Comparação de recursos entre formatos, catálogos e backends de armazenamento