ClickHouse Memory: Tuning max_memory_usage and max_bytes_before_external_group_by


“Memory is the golden key to performance; unlock its potential with precision tuning in ClickHouse, and transform how your large database handles complex join operations.” – ChistaDATA ClickHouse Performance Engineering

Memory management is crucial when working with large databases like ClickHouse, especially for resource-intensive operations such as joins. The max_memory_usage and max_bytes_before_external_group_by settings are essential for controlling memory utilization in ClickHouse. By properly configuring these settings, you can ensure efficient memory usage, prevent out-of-memory errors, and optimize performance.



This setting determines the maximum amount of RAM that a single query can utilize.

Use Case

Consider a scenario where you need to join two large tables, resulting in a massive intermediate result set. If max_memory_usage is set too low, the query may fail due to insufficient memory. On the other hand, setting it too high can lead to the server running out of memory.

Recommended Values

  • Set max_memory_usage to a value that balances the available system RAM with the needs of your largest queries.
  • A good starting point could be 50% of the available RAM divided by the maximum number of concurrent queries.
  • For example, in a system with 64GB RAM and an expectation of running 10 concurrent queries:
SET max_memory_usage = 3GB;



This setting controls the amount of RAM used for GROUP BY operations before ClickHouse starts to spill data to disk.

Use Case

Imagine that you need to run aggregation queries with GROUP BY clauses on large datasets using ClickHouse. If the setting is too low, ClickHouse will utilize temporary disk space, potentially slowing down the query. Conversely, if the setting is set too high, it may result in out-of-memory issues.

Recommended Values

  • Similar to max_memory_usage, this should be a fraction of the available RAM.
  • Start with a value that’s a comfortable portion of max_memory_usage.
  • For example, continuing from the previous scenario:
SET max_bytes_before_external_group_by = 2GB;

How to Tune ClickHouse Memory Parameters

  1. Monitor Current Usage:
    • Use system.query_log to find memory usage of previous queries.
    • Look for queries that are close to the memory limit.
  2. Adjust and Test:
    • Adjust max_memory_usage and max_bytes_before_external_group_by.
    • Run your typical queries and observe performance and memory usage.
    • Ensure that queries aren’t spilling to disk unnecessarily, but also that they aren’t running out of memory.
  3. Balance with Other Settings:
    • Ensure other memory-related settings like max_bytes_before_external_sort are also configured properly.
    • Balance is key: setting one limit too high without adjusting others can lead to imbalances and suboptimal performance.
  4. Observe System Memory:
    • Use tools like htop to monitor overall system memory usage.
    • Ensure that ClickHouse’s memory usage is balanced with other system needs.
  5. Automate Monitoring and Adjustment:
    • Consider scripts or monitoring tools to adjust settings based on system load or specific query patterns.


Tuning max_memory_usage and max_bytes_before_external_group_by is crucial for optimizing memory usage in ClickHouse, particularly for large databases and complex join operations. It involves finding a delicate balance, understanding your workload, and consistently monitoring the system. By configuring these settings correctly, you can achieve optimal performance, efficiently utilizing system resources and ensuring smooth query execution.

To know more about tuning Clickhouse Memory parameters, do read the following articles:

ChistaDATA – Your ClickHouse Partner

Are you struggling with memory management in your large ClickHouse database? Look no further! At ChistaDATA, we specialize in optimizing memory usage to deliver exceptional performance. Our precision tuning techniques will unlock the full potential of your database, transforming how it handles complex join operations.

Say goodbye to frustrating out-of-memory errors and hello to efficient memory utilization. With our expertise, you can ensure smooth query execution and prevent performance bottlenecks.

But don’t just take our word for it. Visit to learn more about how our services can revolutionize your data processing experience. Our team of experts will work closely with you to understand your workload and fine-tune the max_memory_usage and max_bytes_before_external_group_by settings to perfectly balance system resources.

Don’t let memory limitations hold you back. Trust ChistaDATA to take your database performance to new heights. Contact us today and unlock the true potential of your ClickHouse database!

About Shiv Iyer 215 Articles
Open Source Database Systems Engineer with a deep understanding of Optimizer Internals, Performance Engineering, Scalability and Data SRE. Shiv currently is the Founder, Investor, Board Member and CEO of multiple Database Systems Infrastructure Operations companies in the Transaction Processing Computing and ColumnStores ecosystem. He is also a frequent speaker in open source software conferences globally.