> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# parallel_replicas_* session settings

> ClickHouse session settings in the parallel_replicas_* generated group.

These settings are available in [system.settings](https://clickhouse.com/docs/reference/system-tables/settings.md) and are autogenerated from [source](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp).

## parallel\_replicas\_allow\_in\_with\_subquery

Type

Bool

Default

1

If true, subquery for IN will be executed on every follower replica.

## parallel\_replicas\_allow\_materialized\_views

Type

Bool

Default

1

Allow usage of materialized views with parallel replicas

## parallel\_replicas\_allow\_merge\_tables

[Experimental feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#experimental-features)

Type

Bool

Default

0

Allow reading from a `Merge` table with parallel replicas. Effective only together with [parallel\_replicas\_plan\_based](https://clickhouse.com/docs/reference/settings/session-settings/parallel-replicas.md#parallel_replicas_plan_based): the read from the `Merge` table is expanded into a union of the reads from the underlying `MergeTree` tables, which is then distributed like any other union. A `Merge` table is left to a single replica when any of its underlying tables cannot be read that way (a non-`MergeTree` table, a `FINAL` read). Set it to `false` to read every `Merge` table on a single replica, as before the support was added. Experimental.

## parallel\_replicas\_allow\_view\_over\_mergetree

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

Type

Bool

Default

0

Allow parallel replicas to execute the outer query of a simple view over `MergeTree` tables (instead of the view's inner query), improving parallelization across nodes. Also applies to `UNION ALL` views whose branches all read from different `MergeTree` tables.

## parallel\_replicas\_connect\_timeout\_ms

Type

Milliseconds

Default

300

The timeout in milliseconds for connecting to a remote replica during query execution with parallel replicas. If the timeout is expired, the corresponding replicas is not used for query execution

## parallel\_replicas\_count

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

Type

UInt64

Default

0

This is internal setting that should not be used directly and represents an implementation detail of the 'parallel replicas' mode. This setting will be automatically set up by the initiator server for distributed queries to the number of parallel replicas participating in query processing.

## parallel\_replicas\_custom\_key

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

An arbitrary integer expression that can be used to split work between replicas for a specific table.
The value can be any integer expression.

Simple expressions using primary keys are preferred.

If the setting is used on a cluster that consists of a single shard with multiple replicas, those replicas will be converted into virtual shards.
Otherwise, it will behave same as for `SAMPLE` key, it will use multiple replicas of each shard.

The expression is checked against the column-level `SELECT` grants of the user. For a view with `SQL SECURITY DEFINER` or `NONE` it is applied to the columns of the view; the body of the view is read without it.

## parallel\_replicas\_custom\_key\_range\_lower

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

Type

UInt64

Default

0

Allows the filter type `range` to split the work evenly between replicas based on the custom range `[parallel_replicas_custom_key_range_lower, INT_MAX]`.

When used in conjunction with [parallel\_replicas\_custom\_key\_range\_upper](https://clickhouse.com/docs/reference/settings/session-settings/parallel-replicas.md#parallel_replicas_custom_key_range_upper), it lets the filter evenly split the work over replicas for the range `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]`.

Note: This setting will not cause any additional data to be filtered during query processing, rather it changes the points at which the range filter breaks up the range `[0, INT_MAX]` for parallel processing.

## parallel\_replicas\_custom\_key\_range\_upper

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

Type

UInt64

Default

0

Allows the filter type `range` to split the work evenly between replicas based on the custom range `[0, parallel_replicas_custom_key_range_upper]`. A value of 0 disables the upper bound, setting it the max value of the custom key expression.

When used in conjunction with [parallel\_replicas\_custom\_key\_range\_lower](https://clickhouse.com/docs/reference/settings/session-settings/parallel-replicas.md#parallel_replicas_custom_key_range_lower), it lets the filter evenly split the work over replicas for the range `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]`.

Note: This setting will not cause any additional data to be filtered during query processing, rather it changes the points at which the range filter breaks up the range `[0, INT_MAX]` for parallel processing

## parallel\_replicas\_filter\_pushdown

Type

Bool

Default

1

Push a condition standing above the part of the query parallel replicas execute into that part, and into the query the replicas are sent, so that they filter by it as well.

Turn it off to keep the condition above the read on the initiator, as versions before 26.10 did. It is the way out if the push-down misbehaves: the answer does not change either way, only how much work the replicas do and how early they do it.

## parallel\_replicas\_for\_cluster\_engines

Type

Bool

Default

1

Replace table function engines with their -Cluster alternatives

## parallel\_replicas\_for\_non\_replicated\_merge\_tree

Type

Bool

Default

0

If true, ClickHouse will use parallel replicas algorithm also for non-replicated MergeTree tables

## parallel\_replicas\_for\_object\_storage\_tables

Type

Bool

Default

1

Read a table with an object storage engine that has a `-Cluster` table function (`S3`, `AzureBlobStorage`, `HDFS`, `Iceberg`, `IcebergS3`, `IcebergAzure`, `IcebergHDFS`, `IcebergLocal`, `DeltaLake`, `DeltaLakeS3`, `DeltaLakeAzure`, `Hudi`, `Paimon`, `PaimonS3`, `PaimonAzure`, `PaimonHDFS`) over the replicas of `cluster_for_parallel_replicas`, the same way `parallel_replicas_for_cluster_engines` does for the table functions. Has no effect when `parallel_replicas_for_cluster_engines` is disabled.

A replica takes part in the read only if it has the table, and the table must have the same definition on every replica.

## parallel\_replicas\_for\_queries\_with\_multiple\_tables

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

Type

Bool

Default

1

If enabled, parallel replicas can be used for queries joining multiple tables (queries with `JOIN`). If disabled, parallel replicas are not used for such queries, and they are executed without parallel replicas.

The setting affects only queries with `JOIN`, where the non-leftmost side is read in full on every replica. A `UNION` query without a `JOIN` is not affected: each `UNION` branch is an independent single-table read, so parallel replicas remain applicable to it. A `UNION` used as a table expression of a `JOIN` is a part of a query joining multiple tables and is affected. `ARRAY JOIN` does not count as a join between tables.

## parallel\_replicas\_index\_analysis\_only\_on\_coordinator

Type

Bool

Default

1

Index analysis done only on replica-coordinator and skipped on other replicas. Effective only with enabled parallel\_replicas\_local\_plan

This concerns the index analysis that selects the mark ranges a read announces, which is what the coordinator assigns from. It does not cover pruning that happens while the data is read, such as the granule pruning of `enable_join_runtime_filters_index_analysis`: a JOIN runtime filter only exists once the build side has been read, so every replica evaluates its own and prunes its own share, and no coordinator could do it for them.

## parallel\_replicas\_local\_plan

Type

Bool

Default

1

Build local plan for local replica

## parallel\_replicas\_mark\_segment\_size

Type

UInt64

Default

0

Parts virtually divided into segments to be distributed between replicas for parallel reading. This setting controls the size of these segments. Not recommended to change until you're absolutely sure in what you're doing. Value should be in range \[128; 16384]

## parallel\_replicas\_min\_number\_of\_rows\_per\_replica

Type

UInt64

Default

0

Limit the number of replicas used in a query to (estimated rows to read / min\_number\_of\_rows\_per\_replica). The max is still limited by 'max\_parallel\_replicas'

Ignored when `automatic_parallel_replicas_mode` is enabled: the automatic mode decides with its own cost model.

## parallel\_replicas\_mode

Type

ParallelReplicasMode

Default

read\_tasks

Type of filter to use with custom key for parallel replicas. default - use modulo operation on the custom key, range - use range filter on custom key using all possible values for the value type of custom key.

## parallel\_replicas\_plan\_based

[Experimental feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#experimental-features)

Type

Bool

Default

0

Decide whether and where to use parallel replicas by analyzing the query plan, as opposed to the query-tree-based analysis. As a result, a plan fragment is sent to the remote replicas instead of a SQL query. Experimental.

Has no effect on a distributed `INSERT SELECT` ([parallel\_distributed\_insert\_select](https://clickhouse.com/docs/reference/settings/session-settings/parallel.md#parallel_distributed_insert_select) = 2), which ships the whole `INSERT` as a query to every replica: a replica executing that query reads with the query-tree-based implementation, so the initiator, taking part as one more replica, uses it too.

## parallel\_replicas\_prefer\_local\_join

Type

Bool

Default

1

If true, and `JOIN` can be executed with parallel replicas algorithm, and every storage of the `JOIN` part that would otherwise be materialized into a temporary table can be read by each replica on its own, local `JOIN` will be used instead of `GLOBAL JOIN`. That part is the right one, except for a `RIGHT JOIN`, where it is the left one and where every storage has to be eligible for parallel replicas rather than merely `*MergeTree`. A storage under the materialized side of a nested `GLOBAL JOIN`, or under a `GLOBAL IN`, does not count, because the initiator materializes those itself.

## parallel\_replicas\_prefer\_local\_replica

Type

Bool

Default

1

When enabled (default), the local replica is always included in the set of replicas used for parallel reading.
When disabled, the local replica is not given any preference and replicas are selected purely by the load balancing algorithm.
This allows queries with `max_parallel_replicas = 1` to be directed to another host, which can improve cache locality when many short queries are distributed across a cluster.

## parallel\_replicas\_support\_projection

Type

Bool

Default

1

Optimization of projections can be applied in parallel replicas. Effective only with enabled parallel\_replicas\_local\_plan.
