ClickHouse

Memory Limit Exceeded During Aggregation

critical
Resource ContentionUpdated Jan 21, 2026

High-cardinality GROUP BY operations or large JOINs exceed per-query or per-user memory limits, causing query failures with memory limit exceptions.

How to detect:

Detect queries with peak_memory_usage approaching or exceeding max_memory_usage. Monitor system.query_log for exception messages containing 'Memory limit exceeded' and identify queries with high cardinality GROUP BY or JOIN operations. Track MemoryTracking metrics from system.metrics.

Recommended action:

Enable external aggregation (max_bytes_before_external_group_by) to spill to disk. Optimize queries by reducing GROUP BY cardinality, using approximate functions (uniqHLL12 instead of uniqExact), filtering data earlier with PREWHERE, or replacing JOINs with dictionaries. Increase max_memory_usage if appropriate for the workload.