# 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`:

```sql
SET max_threads = 1;
```

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

```text
"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](https://coordinatordb.com/docs/reference/settings/session-settings/max-threads).

## Monitoring query parallelism

Read [`system.processes`](https://coordinatordb.com/docs/reference/system-tables/processes) while another
connection runs the workload:

```sql
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`](https://coordinatordb.com/docs/reference/system-tables/query-log) to compare completed
requests and their duration, row counts, and memory use. That table does not
contain `peak_threads_usage`.