Como resolver a exceção "Too many parts" no ClickHouse

O ClickHouse lança a exceção Too many parts quando um INSERT excederia um limite configurado para o número de partes de dados ativas em uma tabela MergeTree. A exceção geralmente inclui a mensagem Merges are processing significantly slower than inserts.

Cada INSERT síncrono cria pelo menos uma parte de dados. Se uma inserção contiver linhas para vários valores de partição, o ClickHouse poderá criar uma parte para cada partição afetada. A mesclagem em segundo plano combina partes menores em partes maiores, mas, se novas partes forem criadas mais rápido do que o ClickHouse consegue mesclá-las, o número de partes ativas continuará aumentando.

A exceção pode ser causada por qualquer uma destas configurações:

• parts_to_throw_insert, que limita o número de partes ativas em uma única partição.
• max_parts_in_total, que limita o número total de partes ativas em uma tabela.

Use a consulta a seguir para encontrar as partições com o maior número de partes ativas:

SELECT
    database,
    table,
    partition_id,
    count() AS active_parts,
    sum(rows) AS rows,
    formatReadableSize(sum(bytes_on_disk)) AS size_on_disk
FROM system.parts
WHERE active
  AND database = '<database_name>'
  AND table = '<table_name>'
GROUP BY
    database,
    table,
    partition_id
ORDER BY active_parts DESC;

Para verificar o limite aplicado à tabela como um todo por max_parts_in_total, conte todas as partes ativas da tabela:

SELECT
    database,
    table,
    count() AS active_parts,
    sum(rows) AS rows,
    formatReadableSize(sum(bytes_on_disk)) AS size_on_disk
FROM system.parts
WHERE active
  AND database = '<database_name>'
  AND table = '<table_name>'
GROUP BY
    database,
    table;

As causas comuns incluem:

• Inserções síncronas frequentes e pequenas.
• Uma chave de particionamento de alta cardinalidade.
• Inserções que contêm linhas para muitos valores de partição.
• Mesclagens em segundo plano que não conseguem acompanhar devido ao throughput de armazenamento limitado, espaço livre em disco insuficiente ou outra contenção de recursos.

Você pode inspecionar os merges em execução no momento em system.merges e revisar os logs do servidor para identificar falhas de merge.

Agrupe as linhas no cliente em lotes antes de inseri-las. Cada lote deve conter pelo menos 1.000 linhas e, de preferência, entre 10.000 e 100.000 linhas. Procure fazer aproximadamente um INSERT síncrono por segundo. Inserções menos frequentes, porém maiores, criam menos partes e reduzem o trabalho necessário da mesclagem em segundo plano.

Se o batching do lado do cliente não for viável, use inserções assíncronas para que o ClickHouse possa agrupar os dados recebidos no servidor:

INSERT INTO <table_name>
SETTINGS
    async_insert = 1,
    wait_for_async_insert = 1
VALUES (...);

Mantenha wait_for_async_insert = 1 para que o ClickHouse confirme uma inserção somente depois que os dados forem gravados com sucesso.

Use uma chave de particionamento de baixa cardinalidade e evite particionar por valores como identificadores de usuário ou de requisição. O ClickHouse mescla partes apenas dentro da mesma partição, portanto um grande número de partições impede mesclagens eficazes. Para mais informações, consulte Como escolher uma chave de particionamento.

Se as inserções já estiverem adequadamente agrupadas em lotes, verifique o desempenho do armazenamento, o espaço em disco disponível e as tarefas em segundo plano concorrentes. A taxa de merge depende do sistema de armazenamento, do mecanismo da tabela, da chave de ordenação, da compressão e da capacidade disponível de CPU e E/S.

Aumentar parts_to_throw_insert ou max_parts_in_total não resolve a causa da criação excessiva de partes. Limites mais altos podem adiar a exceção, mas também podem aumentar a sobrecarga do sistema de arquivos e dos metadados, além de reduzir o desempenho das consultas. Altere essas configurações somente depois de identificar a causa e confirmar que o sistema tem capacidade suficiente.

Execute a consulta de diagnóstico novamente após alterar a estratégia de insert ou o esquema de particionamento. O número de partes ativas deve se estabilizar e depois diminuir, à medida que as mesclagens em segundo plano colocam o processamento em dia. Continue monitorando falhas de insert, o espaço livre em disco e system.merges até que o backlog seja eliminado.