Escolha um método de acesso
Funções de tabela
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
motor de banco de dados DataLakeCatalog
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
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
Práticas de consulta
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 *. 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
'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 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 Delta change data feed para ver um exemplo de CDF.
Armazene arquivos Parquet em cache localmente
enable_filesystem_cache = 0 ao fazer benchmarking para que os acessos ao cache não mascarem as mudanças entre execuções.
Apache Iceberg
Configurações de leitura
Reduza a latência do catálogo
- Defina iceberg_metadata_async_prefetch_period_ms ao criar a tabela para buscar metadados antecipadamente em segundo plano.
- Defina iceberg_metadata_staleness_ms (26.3+) nas consultas para aceitar metadados ligeiramente desatualizados e, assim, evitar a ida e volta ao catálogo.
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
Gravações no Iceberg
Consulte Gravação em lagos de dados e a referência do motor Iceberg.
Delta Lake
Delta Kernel
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
delta.enableChangeDataFeed). Defina as versões inicial e final nas configurações da consulta. Definir apenas a versão final gera um erro.
_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
Depurar consultas do data lake
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:
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:
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
_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
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
Execute uma consulta com o logging habilitado, force o flush do log e, em seguida, inspecione as entradas desse
query_id:
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
- Primeiros passos — Guia completo, da consulta direta à gravação de dados de volta
- Consultando diretamente — Funções de tabela, motores e variantes de cluster para os quatro formatos
- Conectando-se a catálogos — Configuração do
DataLakeCatalogcom 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