ClickHouse Configuration: Tuning max_insert_threads and max_bytes_before_external_group_by


Configuring max_insert_threads and max_bytes_before_external_group_by in ClickHouse requires an understanding of your server’s hardware capabilities and your specific workload requirements. These settings play a crucial role in how ClickHouse manages memory and parallelism, especially during insert operations and GROUP BY queries.

Here’s a guide on how to configure these parameters effectively:

1. max_insert_threads


  • Purposemax_insert_threads controls the number of threads used for performing INSERT operations in tables using the MergeTree engine. It allows parallel processing of inserts, which can significantly speed up the insertion process.

Factors to Consider

  • CPU Cores: The number of available CPU cores is a key factor. More cores mean more potential for parallel processing.
  • Concurrent Inserts: If you have many concurrent inserts, a higher number of insert threads can improve performance.
  • I/O Capabilities: Ensure your disk I/O can keep up with the increased write load due to parallel inserts.
  • General Guideline: As a starting point, set it to the number of physical CPU cores on the server.
  • Adjust Based on Performance: Monitor system performance and adjust the number if necessary. Be cautious of setting it too high, as it can lead to increased competition for resources.

2. max_bytes_before_external_group_by


  • Purpose: This setting determines the maximum amount of RAM to be used for GROUP BY operations before ClickHouse starts to spill data to the disk. It’s a threshold to control memory usage during aggregation.

Factors to Consider

  • Available Memory: The amount of available RAM on your server is crucial. More memory allows for more data to be processed in-memory.
  • Query Characteristics: Larger GROUP BY queries will require more memory.
  • Workload Type: If your typical workload involves heavy GROUP BY operations, adjusting this setting can have a significant impact on performance.
  • Percentage of RAM: A common approach is to set this to a percentage of your total RAM (e.g., 20-30%).
  • Avoid Excessive Swapping: Set it high enough to keep most of the GROUP BY operation in memory but not so high that it causes the system to start swapping.
  • Balance with Other Settings: Consider the impact on other memory-intensive operations and balance this setting with overall system memory usage.

General Tips

  • Monitoring: Regularly monitor performance metrics to understand the impact of these settings.
  • Incremental Changes: Make changes incrementally and observe their effects.
  • System Resources: Ensure these settings align with other system resource allocations, like max_memory_usage and max_memory_usage_for_all_queries.


Configuring max_insert_threads and max_bytes_before_external_group_by in ClickHouse is a balancing act that depends on your specific hardware setup and workload. Properly tuned, these settings can significantly improve the performance of insert operations and GROUP BY queries, respectively. Regular monitoring and iterative adjustments based on real-world performance data are key to finding the optimal configuration.

About Shiv Iyer 225 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.