> ## 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.

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>Type</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>Default</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          Changeable without restart
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

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

<h2 id="parallel_replicas_allow_in_with_subquery">
  parallel\_replicas\_allow\_in\_with\_subquery
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "1"},{"label": "If true, subquery for IN will be executed on every follower replica"}]}]} />

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

<h2 id="parallel_replicas_allow_materialized_views">
  parallel\_replicas\_allow\_materialized\_views
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.12"},{"label": "1"},{"label": "Allow usage of materialized views with parallel replicas"}]}]} />

Allow usage of materialized views with parallel replicas

<h2 id="parallel_replicas_allow_view_over_mergetree">
  parallel\_replicas\_allow\_view\_over\_mergetree
</h2>

<BetaBadge />

<SettingsInfoBlock type="Bool" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "0"},{"label": "New setting"}]}]} />

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.

<h2 id="parallel_replicas_connect_timeout_ms">
  parallel\_replicas\_connect\_timeout\_ms
</h2>

<SettingsInfoBlock type="Milliseconds" default_value="300" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.6"},{"label": "300"},{"label": "Separate connection timeout for parallel replicas queries"}]}]} />

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 executio

<h2 id="parallel_replicas_count">
  parallel\_replicas\_count
</h2>

<BetaBadge />

<SettingsInfoBlock type="UInt64" default_value="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.

<h2 id="parallel_replicas_custom_key">
  parallel\_replicas\_custom\_key
</h2>

<BetaBadge />

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.

<h2 id="parallel_replicas_custom_key_range_lower">
  parallel\_replicas\_custom\_key\_range\_lower
</h2>

<BetaBadge />

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.6"},{"label": "0"},{"label": "Add settings to control the range filter when using parallel replicas with dynamic shards"}]}]} />

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](/docs/reference/settings/session-settings/parallel-replicas#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.

<h2 id="parallel_replicas_custom_key_range_upper">
  parallel\_replicas\_custom\_key\_range\_upper
</h2>

<BetaBadge />

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.6"},{"label": "0"},{"label": "Add settings to control the range filter when using parallel replicas with dynamic shards. A value of 0 disables the upper limit"}]}]} />

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](/docs/reference/settings/session-settings/parallel-replicas#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

<h2 id="parallel_replicas_filter_pushdown">
  parallel\_replicas\_filter\_pushdown
</h2>

<BetaBadge />

<SettingsInfoBlock type="Bool" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.2"},{"label": "0"},{"label": "New setting"}]}]} />

Allow pushing down filters to part of query which parallel replicas choose to execute

<h2 id="parallel_replicas_for_cluster_engines">
  parallel\_replicas\_for\_cluster\_engines
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.3"},{"label": "1"},{"label": "New setting."}]}]} />

Replace table function engines with their -Cluster alternatives

<h2 id="parallel_replicas_for_non_replicated_merge_tree">
  parallel\_replicas\_for\_non\_replicated\_merge\_tree
</h2>

<SettingsInfoBlock type="Bool" default_value="0" />

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

<h2 id="parallel_replicas_index_analysis_only_on_coordinator">
  parallel\_replicas\_index\_analysis\_only\_on\_coordinator
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.12"},{"label": "1"},{"label": "Index analysis done only on replica-coordinator and skipped on other replicas. Effective only with enabled parallel_replicas_local_plan"}]}, {"id": "row-2","items": [{"label": "24.10"},{"label": "1"},{"label": "Index analysis done only on replica-coordinator and skipped on other replicas. Effective only with enabled parallel_replicas_local_plan"}]}]} />

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

<h2 id="parallel_replicas_insert_select_local_pipeline">
  parallel\_replicas\_insert\_select\_local\_pipeline
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.5"},{"label": "1"},{"label": "Use local pipeline during distributed INSERT SELECT with parallel replicas. Currently disabled due to performance issues"}]}, {"id": "row-2","items": [{"label": "25.4"},{"label": "0"},{"label": "Use local pipeline during distributed INSERT SELECT with parallel replicas. Currently disabled due to performance issues"}]}]} />

Use local pipeline during distributed INSERT SELECT with parallel replicas

<h2 id="parallel_replicas_local_plan">
  parallel\_replicas\_local\_plan
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.9"},{"label": "0"},{"label": "Use local plan for local replica in a query with parallel replicas"}]}, {"id": "row-2","items": [{"label": "24.11"},{"label": "1"},{"label": "Use local plan for local replica in a query with parallel replicas"}]}, {"id": "row-3","items": [{"label": "24.10"},{"label": "1"},{"label": "Use local plan for local replica in a query with parallel replicas"}]}]} />

Build local plan for local replica

<h2 id="parallel_replicas_mark_segment_size">
  parallel\_replicas\_mark\_segment\_size
</h2>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.9"},{"label": "0"},{"label": "Value for this setting now determined automatically"}]}, {"id": "row-2","items": [{"label": "24.1"},{"label": "128"},{"label": "Add new setting to control segment size in new parallel replicas coordinator implementation"}]}]} />

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]

<h2 id="parallel_replicas_min_number_of_rows_per_replica">
  parallel\_replicas\_min\_number\_of\_rows\_per\_replica
</h2>

<SettingsInfoBlock type="UInt64" default_value="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'

<h2 id="parallel_replicas_mode">
  parallel\_replicas\_mode
</h2>

<SettingsInfoBlock type="ParallelReplicasMode" default_value="read_tasks" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "read_tasks"},{"label": "This setting was introduced as a part of making parallel replicas feature Beta"}]}]} />

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.

<h2 id="parallel_replicas_only_with_analyzer">
  parallel\_replicas\_only\_with\_analyzer
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.2"},{"label": "1"},{"label": "Parallel replicas is supported only with analyzer enabled"}]}]} />

The analyzer should be enabled to use parallel replicas. With disabled analyzer query execution fallbacks to local execution, even if parallel reading from replicas is enabled. Using parallel replicas without the analyzer enabled is not supported

<h2 id="parallel_replicas_plan_based">
  parallel\_replicas\_plan\_based
</h2>

<ExperimentalBadge />

<SettingsInfoBlock type="Bool" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": "0"},{"label": "New setting"}]}]} />

Express the parallel replicas local/remote boundary as a plan transformation. The planner builds a plain local plan; a split step is then inserted above the reading step and replaced with a `UNION` of a local read and a remote read of the part of the plan below the split step, so that fragment runs on the replicas while the rest runs on the coordinator. Experimental, takes precedence over `parallel_replicas_local_plan`.

<h2 id="parallel_replicas_prefer_local_join">
  parallel\_replicas\_prefer\_local\_join
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.2"},{"label": "1"},{"label": "If true, and JOIN can be executed with parallel replicas algorithm, and all storages of right JOIN part are *MergeTree, local JOIN will be used instead of GLOBAL JOIN."}]}]} />

If true, and JOIN can be executed with parallel replicas algorithm, and all storages of right JOIN part are \*MergeTree, local JOIN will be used instead of GLOBAL JOIN.

<h2 id="parallel_replicas_prefer_local_replica">
  parallel\_replicas\_prefer\_local\_replica
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.5"},{"label": "1"},{"label": "New setting. When disabled, replicas for parallel reading are selected purely by the load balancing algorithm without forcing the local replica into the set."}]}]} />

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.

<h2 id="parallel_replicas_support_projection">
  parallel\_replicas\_support\_projection
</h2>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.8"},{"label": "1"},{"label": "New setting. Optimization of projections can be applied in parallel replicas. Effective only with enabled parallel_replicas_local_plan and aggregation_in_order is inactive."}]}]} />

Optimization of projections can be applied in parallel replicas. Effective only with enabled parallel\_replicas\_local\_plan and aggregation\_in\_order is inactive.