ClickHouse Performance: Tuning ClickHouse for Maximum CPU Efficiency


For improving ClickHouse CPU efficiency and optimizing it for parallel query operations, the process involves careful adjustment of several server parameters. These settings help in utilizing CPU resources more effectively while balancing the load across multiple cores.

Runbook to Tune ClickHouse for CPU Efficiency

Here’s a detailed guide on the key parameters to tune for CPU efficiency in ClickHouse:

1. max_threads

  • Description: Controls the maximum number of threads used for processing a single query. It determines how many CPU cores can be used in parallel.
  • Recommended Value: Set it to the number of physical cores available on the server. However, if your workload consists of many concurrent queries, you might want to set this lower to leave room for other queries.

2. max_block_size

  • Description: Determines the maximum number of rows in a block for processing. Larger block sizes can reduce overhead but increase the per-thread workload.
  • Recommended Value: The default is usually adequate (65,536), but you can experiment with larger values if your CPU cores are powerful and you’re running large analytical queries.

3. min_insert_block_size_rows and min_insert_block_size_bytes

  • Description: These settings control the minimum number of rows or bytes in a block to be inserted. Larger blocks can be more CPU-efficient.
  • Recommended Value: Adjust these values based on your typical insert sizes. Setting them too high might delay the appearance of rows in real-time insert scenarios.

4. max_insert_threads

  • Description: This setting allows parallel insert processing for the MergeTree engine.
  • Recommended Value: Can be set to the number of available CPU cores, but should be balanced against max_threads to avoid overloading the server during heavy insert operations.

5. mark_cache_size

  • Description: Defines the size of the mark cache, which stores index marks for primary and secondary indices. A larger cache can reduce CPU usage for index reading.
  • Recommended Value: Adjust based on your server’s total RAM. A larger cache reduces disk I/O but uses more memory.

6. number_of_free_entries_in_pool_to_lower_max_size_of_merge

  • Description: This parameter helps in controlling the size of merges in the background merge process.
  • Recommended Value: Lowering this value can reduce CPU and I/O load during merges but might lead to more fragmented data.

7. load_balancing

  • Description: This parameter is important in a distributed setup. It defines the strategy for distributing queries across cluster nodes.
  • Recommended Value: Options like ‘random’, ‘nearest_hostname’, or ‘in_order’ should be chosen based on the specific cluster setup and network topology.

8. group_by_two_level_threshold and group_by_two_level_threshold_bytes

  • Description: These settings control when ClickHouse switches to a two-level aggregation method for GROUP BY queries, which can be more CPU-efficient for large queries.
  • Recommended Value: The defaults are generally good, but for very large datasets, you might want to lower these thresholds to activate two-level aggregation sooner.


Tuning ClickHouse for CPU efficiency involves finding the right balance between maximizing parallelism and not overwhelming the CPU with too many concurrent operations. It’s important to consider the specific characteristics of your workload and hardware. Regular monitoring and iterative adjustments based on observed performance are key to achieving optimal CPU utilization in ClickHouse. Remember, changes in these settings can have significant effects on performance, so it’s advisable to test any adjustments in a controlled environment before applying them to production.

To know more about ClickHouse CPU Usage and Troubleshooting, do consider reading the following articles

  1. Troubleshooting High CPU Usage in ClickHouse
  2. ClickHouse Troubleshooting: Understanding Estimated I/O and CPU Costs
  3. ClickHouse Performance: Choosing the Right CPU Infrastructure
About Shiv Iyer 216 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.