How do I fix ClickHouse "Too many parts"?

Code: 252. DB::Exception: Too many parts (3001). Merges are processing
significantly slower than inserts. (TOO_MANY_PARTS)

ClickHouse is known for ingesting millions of rows per second, so it's surprising when it rejects inserts from an app writing a few hundred rows per second. The reason is almost never volume. It's how many separate inserts you send.

Why it happens

In a MergeTree table, every INSERT creates at least one new data part on disk: a directory of sorted, compressed column files. Background merges continually combine small parts into bigger ones, which keeps reads fast.

If you send many small inserts (one row per HTTP request, a few rows every few milliseconds, one insert per Kafka message), parts are created faster than merges can combine them. ClickHouse protects itself:

• above parts_to_delay_insert active parts in a partition, inserts are artificially slowed;
• above parts_to_throw_insert, they're rejected with TOO_MANY_PARTS.

Since ClickHouse 23.6 those defaults are 1,000 and 3,000 per partition (previously 150 and 300, which is why older blog posts give lower numbers).

Check the part counts

SELECT database, table, partition, count() AS parts
FROM system.parts
WHERE active
GROUP BY database, table, partition
ORDER BY parts DESC
LIMIT 10;

SELECT table, elapsed, progress, num_parts
FROM system.merges;

Thousands of tiny parts in the current partition confirm it. If merges are running constantly and falling behind, it's also a CPU and disk sizing question.