Mastering Concurrency in ClickHouse by Optimizing ClickHouse Thread Performance


“Unlock unparalleled efficiency and speed in your data operations; this runbook is your key to mastering ClickHouse thread performance and conquering high concurrency with confidence.” – ChistaDATA Performance Engineering

ClickHouse is a high-performance columnar database that can handle massive amounts of data. To achieve this, it uses multiple threads to parallelize its operations. This runbook will guide you through the steps to tune ClickHouse’s thread performance to ensure optimal utilization of resources.


  • A working ClickHouse installation.
  • Administrative rights to the ClickHouse server.
  • Basic understanding of the ClickHouse configuration files.

Runbook to optimize ClickHouse Thread Performance

  1. Assess the Current Configuration:
    • Check the current number of threads ClickHouse is using:
SELECT name, value FROM system.settings WHERE name LIKE 'max_threads';
  1. Determine Optimal Thread Count:
    • Ideally, ClickHouse should utilize all available CPU cores for maximum parallelism.
    • Use nproc or lscpu to determine the number of available cores.
  2. Adjust max_threads Setting:
    • Edit the ClickHouse configuration file, usually located at /etc/clickhouse-server/config.xml.
    • Find the max_threads setting under the <yandex> section.
    • Set its value to the number of available cores or a number based on your workload.
  1. Tune Background Threads:
    • ClickHouse uses background threads for tasks like merges, fetches, and replications.
    • Adjust the following settings as needed:
      • background_pool_size: Determines the number of threads for background operations.
      • background_schedule_pool_size: Specifies the number of threads for scheduled tasks.
    • Ensure these values are not set too high, as they can compete with query threads for resources.
  2. Monitor Thread Activity:
    • Utilize ClickHouse’s monitoring capabilities:
SELECT * FROM system.metrics WHERE metric LIKE '%Thread%';
  • Monitor the number of active threads, queued threads, and other relevant metrics.
  1. Check for Thread Contention:
    • If there’s a high level of thread contention, it can hinder performance.
    • Investigate using monitoring tools such as perf, looking for high counts on events related to thread locks or contention.
  2. Optimize Queries:
    • Poorly optimized queries can waste thread resources.
    • Use the system.query_log table to identify long-running or resource-intensive queries.
    • Optimize these queries, e.g., by rewriting them, adding indexes, or adjusting table structures.
  3. Adjust OS-Level Thread Settings:
    • Ensure the operating system is also optimized for high concurrency.
    • Check and increase the limit on open files (ulimit -n).
    • Adjust thread stack size if necessary.
  4. Review Changes & Test:
    • After making configuration changes, always restart ClickHouse:
sudo systemctl restart clickhouse-server
  • Test the system’s performance using benchmarking tools or real-world workloads.
  • Monitor resource utilization, especially CPU. Ensure it’s not consistently at 100%, indicating potential overutilization.


Tuning thread performance in ClickHouse is crucial for handling high concurrency and large volumes of data efficiently. Regularly review and adjust settings as your data and workload evolve. Properly tuned threads can significantly improve query speeds, ensuring that ClickHouse operates at its full potential.

To know more about ClickHouse Threads, do read the following articles: 

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