max_threads
The maximum number of query processing threads, excluding threads for retrieving data from remote servers (see the ‘max_distributed_connections’ parameter). This parameter applies to threads that perform the same stages of the query processing pipeline in parallel. For example, when reading from a table, if it is possible to evaluate expressions with functions, filter withWHERE and pre-aggregate for GROUP BY in parallel using at least ‘max_threads’ number of threads, then ‘max_threads’ are used.
For queries that are completed quickly because of a LIMIT, you can set a lower ‘max_threads’.
For example, if the necessary number of entries are located in every block and max_threads = 8, then 8 blocks are retrieved, although it would have been enough to read just one.
The smaller the max_threads value, the less memory is consumed.
The max_threads setting by default matches the number of hardware threads (number of CPU cores) available to ClickHouse.
As a special case, for x86 processors with less than 32 CPU cores and SMT (e.g. Intel HyperThreading), ClickHouse uses the number of logical cores (= 2 x physical core count) by default.
Without SMT (e.g. Intel HyperThreading), this corresponds to the number of CPU cores.
For ClickHouse Cloud users, the default value will display as auto(N) where N matches the vCPU size of your service e.g. 2vCPU/8GiB, 4vCPU/16GiB etc.
See the settings tab in the Cloud console for a list of all service sizes.
max_threads_for_indexes
The maximum number of threads process indices.max_threads_min_free_memory_per_thread
Lowersmax_threads when the server is under memory pressure, to avoid starting highly-parallel queries that are likely to hit the memory limit.
Free memory is computed as the server’s max_server_memory_usage minus the memory currently tracked by the global memory tracker. If that free memory is less than max_threads multiplied by this value, max_threads is reduced to the largest N such that N * value <= free_memory, with a minimum of 1. Free memory is taken once per query, when its plan is built, so that all parts of the query are planned with the same number of threads.
Set to 0 to disable this limit.
For example, with the default of 1 GiB and 32 GiB of free memory, max_threads is capped at 32; with 1 GiB of free memory it falls back to 1.
This setting applies to read-side parallelism (SELECT, UNION, INTERSECT/EXCEPT, and the SELECT side of INSERT ... SELECT). For the write side, see max_insert_threads_min_free_memory_per_thread.