Query Parallelism ​

CoordinatorDB can use several threads for eligible large scan aggregates. max_threads sets a ceiling on the total number of threads used by one query. It does not guarantee that a query uses the entire allowance.

Controlling query parallelism ​

Choose the limit for the workload:

• 1 requests serial execution.
• 0, the default, selects the available hardware count capped at eight total query threads.
• An explicit value from 2 through 64 allows that many total query threads, subject to available hardware and the configured server ceiling.

The count includes the query's main thread. Some query shapes remain serial, and a small input may not benefit from additional threads. Compare results on the actual workload before choosing a larger value.

On the server, select a database and change its persisted default with SET:

SET max_threads = 1;

SELECT name, value FROM system.settings WHERE name = 'max_threads' FORMAT csv;

"max_threads","1"

The change requires autocommit and no active transactions in that database. Other clients observe the committed setting before later requests. Resource limits are sampled once per request, so changing the value inside a batch affects later requests.

An embedded connection uses PRAGMA max_threads = value. See the max_threads reference.

Monitoring query parallelism ​

Read system.processes while another connection runs the workload:

SELECT query_id, query, peak_threads_usage, memory_usage
FROM system.processes
ORDER BY query_id
FORMAT csv;

peak_threads_usage reports the largest total thread count observed for an active request. Serial execution reports one. The rows depend on the requests currently running; the observing query can appear in its own result.

Use system.query_log to compare completed requests and their duration, row counts, and memory use. That table does not contain peak_threads_usage.