ClickHouse distributed GROUP BY partial results under timeout_overflow_mode break

Short answer

No. ClickHouse does not guarantee deterministic merging of partial GROUP BY results when timeout_overflow_mode='break' interrupts shards unevenly. In ClickHouse 23.x and later, treat this mode as a best-effort partial-result mechanism, not a correctness-stable contract. Avoid it for exact billing, compliance, or SLA aggregates.

Likely explanation

In a distributed GROUP BY, each shard computes local partial aggregate states and sends them to the initiator. With timeout_overflow_mode='break', the initiator stops waiting and merges whichever states have arrived. Because cancellation is asynchronous, shards interrupted mid-aggregation may contribute partial states, no states, or fail to transmit. The set of contributing shards can therefore vary between runs.

Confirmed facts vs. version-dependent assumptions

• Confirmed: Additive aggregates (count, sum, min, max) merge correctly only for states that arrive. Missing shard data yields missing groups or undercounts.
• Confirmed: Without ORDER BY, output row order is unspecified. Repeated timed runs can differ in row count and values.
• Assumption to verify: The exact interruption semantics may depend on cluster topology, replication, and settings such as distributed_aggregation_memory_efficient. Do not assume 23.x behavior is identical across later releases without testing on your target version.

Steps for this case

If deterministic results are required, let the query complete:

1. Raise max_execution_time or remove the timeout for correctness-critical queries.
2. Push selective filters to reduce shard work.
3. Preaggregate with materialized views, or query shards separately and merge deterministically.
4. If partial results are acceptable for exploration, label them clearly and compare against a full-completion baseline.

Verification

To confirm nondeterminism on your cluster, run the same timed query repeatedly on unchanged data and compare row counts, group checksums, and aggregate sums:

SELECT key, count(), sum(metric)
FROM distributed_table
GROUP BY key
SETTINGS max_execution_time = 5, timeout_overflow_mode = 'break';

Inspect system.query_log for per-shard elapsed times and cancellation events. Compare against a baseline run with a higher timeout to quantify missing groups and undercounts.