A ingestão eficiente de dados é a base de implantações do ClickHouse com alto desempenho. Selecionar a estratégia de inserção correta pode afetar drasticamente a taxa de transferência, o custo e a confiabilidade. Esta seção apresenta melhores práticas, trade-offs e opções de configuração para ajudar você a tomar a decisão certa para a sua carga de trabalho.
Inserções síncronas por padrão
Use inserções síncronas se puder agrupar os dados em lotes no clienteCaso contrário, veja Inserções assíncronas abaixo. Etapas no lado do cliente
Inserções em lote, se síncronas
Independentemente do tamanho das suas inserções, recomendamos manter o número de consultas de inserção em cerca de uma consulta de inserção por segundo. O motivo dessa recomendação é que as partes criadas são mescladas em partes maiores em segundo plano (para otimizar seus dados para consultas de leitura), e enviar consultas de inserção demais por segundo pode levar a situações em que a mesclagem em segundo plano não consegue acompanhar o número de novas partes. No entanto, você pode usar uma taxa maior de consultas de inserção por segundo ao usar inserções assíncronas (veja Inserções assíncronas). Garanta retentativas idempotentes
- A inserção foi bem-sucedida, mas o cliente nunca recebeu uma confirmação devido a uma interrupção na rede.
- A inserção falhou no lado do servidor e gerou timeout.
Em ambos os casos, é seguro repetir a inserção — desde que o conteúdo e a ordem do lote permaneçam idênticos. Por esse motivo, é fundamental que os clientes façam retentativas de forma consistente, sem modificar nem reordenar os dados.
Escolha o destino certo para a inserção
- Fazer inserção diretamente em uma tabela MergeTree ou ReplicatedMergeTree. Essa é a opção mais eficiente quando o cliente consegue fazer balanceamento de carga entre os shards. Com
internal_replication = true, o ClickHouse gerencia a replicação de forma transparente.
- Fazer inserção em uma tabela distribuída. Isso permite que os clientes enviem dados para qualquer nó e deixem o ClickHouse encaminhá-los ao shard correto. É mais simples, mas tem desempenho um pouco inferior devido à etapa adicional de encaminhamento.
internal_replication = true continua sendo recomendado.
No ClickHouse Cloud, todos os nós leem e gravam no mesmo shard. As inserções são balanceadas automaticamente entre os nós. Você pode simplesmente enviar as inserções para o endpoint exposto.
Escolher o formato de entrada certo é crucial para uma ingestão eficiente de dados no ClickHouse. Com mais de 70 formatos compatíveis, selecionar a opção de melhor desempenho pode impactar significativamente a velocidade de inserção, o uso de CPU e memória e a eficiência geral do sistema.
Embora a flexibilidade seja útil para engenharia de dados e importações baseadas em arquivos, os aplicativos devem priorizar formatos voltados para desempenho:
- Formato nativo (recomendado): O mais eficiente. Colunar, com necessidade mínima de parsing no lado do servidor. Usado por padrão nos clientes Go e Python.
- RowBinary: Formato eficiente baseado em linhas, ideal se a transformação para o modelo colunar for difícil no lado do cliente. Usado pelo cliente Java.
- JSONEachRow: Fácil de usar, mas caro de parsear. Adequado para casos de uso de baixo volume ou integrações rápidas.
A compactação desempenha um papel fundamental na redução da sobrecarga de rede, na aceleração de inserções e na diminuição dos custos de armazenamento no ClickHouse. Quando usada de forma eficaz, ela melhora o desempenho da ingestão sem exigir mudanças no formato ou no esquema dos dados.
Compactar os dados de inserção reduz o tamanho do payload enviado pela rede, minimizando o consumo de largura de banda e acelerando a transmissão.
Para inserções, a compactação é especialmente eficaz quando usada com o formato Native, que já corresponde ao modelo interno de armazenamento colunar do ClickHouse. Nessa configuração, o servidor pode descompactar e armazenar os dados diretamente, com o mínimo de transformação.
Use LZ4 para velocidade, ZSTD para taxa de compressão
- LZ4: Rápido e leve. Reduz significativamente o tamanho dos dados com sobrecarga mínima de CPU, sendo ideal para inserções com alto throughput e o padrão na maioria dos clientes ClickHouse.
- ZSTD: Maior taxa de compressão, mas com uso mais intenso de CPU. É útil quando os custos de transferência de rede são altos — como em cenários entre regiões ou entre provedores de Cloud — embora aumente ligeiramente a capacidade de processamento no lado do cliente e o tempo de descompressão no lado do servidor.
Boa prática: use LZ4, a menos que você tenha largura de banda limitada ou incorra em custos de egresso de dados — nesse caso, considere ZSTD.
Em testes do benchmark FastFormats, inserções Native comprimidas com LZ4 reduziram o tamanho dos dados em mais de 50%, diminuindo o tempo de ingestão de 150s para 131s em um conjunto de dados de 5,6 GiB. Ao mudar para ZSTD, o mesmo conjunto de dados foi comprimido para 1,69 GiB, mas o tempo de processamento no lado do servidor aumentou ligeiramente. A compressão reduz o uso de recursos
Pré-ordene se o custo for baixo
Não é recomendável enviar muitos batches pequenos no modo síncrono, pois isso leva à criação de muitas partes. Isso resultará em baixo desempenho de consulta e em erros de “too many part”. async_insert.
As inserções assíncronas têm suporte nas interfaces HTTP e TCP nativo.
Quando habilitadas (async_insert = 1), as inserções são mantidas em buffer e gravadas em disco somente quando uma das condições de flush é atendida:
O primeiro limite atingido aciona o flush.
Esse processo de batching é invisível para os clientes e ajuda o ClickHouse a mesclar com eficiência o tráfego de inserções de várias fontes. No entanto, até que ocorra um flush, os dados não podem ser consultados. É importante destacar que há vários buffers para cada combinação de formato de insert e configurações e, em clusters, os buffers são mantidos por nó, o que possibilita um controle granular em ambientes multilocatários. Fora isso, a mecânica de inserção é idêntica à descrita para inserções síncronas.
Escolhendo um modo de retorno
wait_for_async_insert.
Quando definida como 1 (o padrão), o ClickHouse só confirma a inserção depois que os dados são gravados com sucesso em disco. Isso garante fortes garantias de durabilidade e torna o tratamento de erros simples: se algo der errado durante o flush, o erro é retornado ao cliente. Esse modo é recomendado para a maioria dos cenários de produção, especialmente quando falhas de inserção precisam ser rastreadas com confiabilidade.
Benchmarks mostram que isso escala bem com a concorrência — esteja você executando 200 ou 500 clientes — graças às inserções adaptativas e ao comportamento estável na criação de partes.
Definir wait_for_async_insert = 0 habilita o modo “fire-and-forget”. Nesse caso, o servidor confirma a inserção assim que os dados são colocados no buffer, sem esperar que cheguem ao armazenamento.
Isso oferece inserções com latência ultrabaixa e throughput máximo, ideal para dados de alta velocidade e baixa criticidade. No entanto, isso traz desvantagens: não há garantia de que os dados serão persistidos, os erros só aparecem durante o flush, e não há fila de dead-letter para inserções com falha — rastrear falhas exige inspecionar os logs do servidor e as tabelas do sistema posteriormente. Use esse modo apenas se o seu workload puder tolerar perda de dados.
Benchmarks também demonstram redução substancial de partes e menor uso de CPU quando os flushes do buffer são pouco frequentes (por exemplo, a cada 30 segundos), mas o risco de falha silenciosa permanece.
Nossa recomendação enfática é usar async_insert=1,wait_for_async_insert=1 ao usar inserções assíncronas. Usar wait_for_async_insert=0 é muito arriscado porque seu cliente de INSERT pode não perceber se houver erros, e também pode causar uma possível sobrecarga se o cliente continuar gravando rapidamente em uma situação em que o servidor ClickHouse precise desacelerar as gravações e criar alguma contrapressão para garantir a confiabilidade do serviço.
Inserts assíncronos adaptativos
async_insert_use_adaptive_busy_timeout). Em vez de um intervalo de flush fixo, o timeout se ajusta dinamicamente entre um mínimo (async_insert_busy_timeout_min_ms, padrão de 50 ms) e um máximo (async_insert_busy_timeout_max_ms, padrão de 200 ms ou 1000 ms no Cloud), com base na taxa de chegada dos dados.
Quando os dados chegam com frequência, o timeout fica mais próximo do mínimo para fazer o flush mais cedo e reduzir a latência de ponta a ponta. Quando os dados são esparsos, ele aumenta em direção ao máximo para acumular lotes maiores. Isso é especialmente útil no modo padrão (wait_for_async_insert=1), em que um timeout fixo alto faria os clientes ficarem bloqueados durante todo o intervalo, mesmo quando os dados já estivessem prontos para flush.
A validação do schema e o parsing dos dados acontecem durante o flush do buffer, não quando o insert é recebido. Se qualquer linha em uma consulta de insert tiver erro de parsing ou de tipo, nenhum dado dessa consulta é gravado — todo o payload da consulta é rejeitado. No modo padrão (wait_for_async_insert=1), o erro é retornado ao cliente. No modo fire-and-forget, os erros são gravados nos logs do servidor e na tabela system.asynchronous_inserts.
Cada flush cria pelo menos uma parte para cada valor distinto da chave de particionamento no buffer. Mesmo em tabelas sem chave de particionamento, um único flush pode produzir várias partes se os dados em buffer excederem max_insert_block_size (padrão: ~1 milhão de linhas).
Apesar de usar async inserts, você ainda pode encontrar erros de “too many parts” se a chave de particionamento tiver alta cardinalidade. Desduplicação e confiabilidade
Habilitando inserções assíncronas
-
Habilite as inserções assíncronas no nível do usuário. Este exemplo usa o usuário
default; se você criar outro usuário, substitua pelo respectivo nome de usuário:
-
Você pode especificar as configurações de inserção assíncrona usando a cláusula SETTINGS nas consultas de inserção:
-
Você também pode especificar as configurações de inserção assíncrona como parâmetros de conexão ao usar um cliente ClickHouse de uma linguagem de programação.
Por exemplo, veja como fazer isso em uma string de conexão JDBC ao usar o driver JDBC Java do ClickHouse para se conectar ao ClickHouse Cloud:
As inserções assíncronas não se aplicam a consultas INSERT INTO ... SELECT. Quando a inserção contém uma cláusula SELECT, a consulta é sempre executada de forma síncrona, independentemente da configuração async_insert.
Esvaziando os buffers ao encerrar
- Nenhuma alteração de DDL é necessária. As inserções assíncronas são transparentes — você habilita uma configuração, sem criar tabelas adicionais.
- Buffer por formato de consulta. As inserções assíncronas mantêm buffers separados para cada combinação única de formato de consulta e configurações, permitindo políticas de flush mais granulares. As tabelas Buffer usam um único buffer por tabela de destino.
- Durabilidade. No modo padrão (
wait_for_async_insert=1), os dados são confirmados em disco antes de o cliente receber a confirmação. As tabelas Buffer funcionam no estilo fire-and-forget — os dados em buffer são perdidos em caso de falha.
- Comportamento em cluster. Em clusters, os buffers de inserção assíncrona são mantidos por nó. As tabelas Buffer exigem criação explícita em cada nó.
Escolha uma interface: HTTP ou nativa
Content-Encoding: lz4), a compressão é aplicada ao payload inteiro, e não a blocos de dados individuais. Essa interface costuma ser preferida em ambientes nos quais simplicidade de protocolo, balanceamento de carga ou ampla compatibilidade de formatos são mais importantes do que desempenho bruto.
Para uma descrição mais detalhada dessas interfaces, consulte aqui. 
