> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Saiba como diagnosticar e resolver a exceção "Too many parts" agrupando inserts em lotes, usando inserts assíncronos e escolhendo uma chave de particionamento apropriada.

<div id="what-the-exception-means">
  ## O que a exceção significa
</div>

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`](/pt-BR/reference/settings/merge-tree-settings/parts-to#parts_to_throw_insert), que limita o número de partes ativas em uma única partição.
* [`max_parts_in_total`](/pt-BR/reference/settings/merge-tree-settings/max-parts#max_parts_in_total), que limita o número total de partes ativas em uma tabela.

<div id="diagnose-the-cause">
  ## Diagnostique a causa
</div>

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

```sql theme={null}
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:

```sql theme={null}
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`](/pt-BR/reference/system-tables/merges) e revisar os logs do servidor para identificar falhas de merge.

<div id="resolve-the-exception">
  ## Resolva a exceção
</div>

<div id="batch-synchronous-inserts">
  ### Inserções síncronas em lote
</div>

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.

<div id="use-asynchronous-inserts">
  ### Use inserções assíncronas
</div>

Se o batching do lado do cliente não for viável, use [inserções assíncronas](/pt-BR/concepts/best-practices/selecting-an-insert-strategy#asynchronous-inserts) para que o ClickHouse possa agrupar os dados recebidos no servidor:

```sql theme={null}
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.

<div id="review-the-partitioning-key">
  ### Revise a chave de particionamento
</div>

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](/pt-BR/concepts/best-practices/partitioning-keys).

<div id="investigate-merge-bottlenecks">
  ### Investigue gargalos de merge
</div>

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.

<div id="avoid-increasing-part-limits-as-the-primary-fix">
  ### Evite aumentar os limites de partes como correção principal
</div>

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.

<div id="verify-the-recovery">
  ## Verifique a recuperação
</div>

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`](/pt-BR/reference/system-tables/merges) até que o backlog seja eliminado.