> ## 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_* 会话设置

> 位于自动生成的 parallel_replicas_* 组中的 ClickHouse 会话设置。

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
  }}>类型</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>默认值</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          无需重启即可更改
        </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 版功能。 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        了解更多。
                    </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 功能。 <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">了解详情。</a></u>
        </div>;
};

这些设置可在 [system.settings](/docs/zh/reference/system-tables/settings) 中查看，并由 [源文件](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) 自动生成。

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "1"},{"label": "如果为 true，则 IN 子查询会在每个 follower 副本上执行"}]}]} />

如果为 true，则 IN 子查询会在每个 follower 副本上执行。

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.12"},{"label": "1"},{"label": "允许并行副本使用 materialized views"}]}]} />

允许并行副本使用 materialized views

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

<BetaBadge />

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

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

允许并行副本在基于 `MergeTree` 表的简单视图上执行外层查询 (而非视图的内部查询) ，从而提高节点间的并行化能力。同样适用于 `UNION ALL` 视图，前提是其所有分支都从不同的 `MergeTree` 表读取。

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

<SettingsInfoBlock type="毫秒" default_value="300" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.6"},{"label": "300"},{"label": "并行副本查询的独立连接超时"}]}]} />

使用并行副本执行查询时，连接远程副本的超时时间，单位为毫秒。如果发生超时，则不会使用相应的副本执行查询

<div id="parallel_replicas_count">
  ## parallel\_replicas\_count
</div>

<BetaBadge />

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

这是一个不应直接使用的内部设置，用于表示“并行副本”模式的实现细节。对于分布式查询，发起服务器会自动将此设置设为参与查询处理的并行副本数。

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

<BetaBadge />

可用于在特定表的各个副本之间分摊工作的任意整数表达式。
该值可以是任意整数表达式。

优先使用基于主键的简单表达式。

如果该设置用于由单个分片和多个副本组成的集群，这些副本将被转换为虚拟分片。
否则，其行为将与 `SAMPLE` 键相同，即会使用每个分片的多个副本。

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

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.6"},{"label": "0"},{"label": "新增了相关设置，用于在并行副本配合 dynamic shards 使用时控制 `range` 过滤器"}]}]} />

允许 `range` 类型的过滤器根据自定义范围 `[parallel_replicas_custom_key_range_lower, INT_MAX]`，在各副本之间均匀分配工作负载。

与 [parallel\_replicas\_custom\_key\_range\_upper](/docs/zh/reference/settings/session-settings/parallel-replicas#parallel_replicas_custom_key_range_upper) 配合使用时，它可让该过滤器针对范围 `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]` 在各副本之间均匀分配工作负载。

注意：此设置不会在查询处理期间额外过滤任何数据，而只是改变 `range` 过滤器为并行处理拆分范围 `[0, INT_MAX]` 时所使用的分界点。

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

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.6"},{"label": "0"},{"label": "新增了用于在结合 dynamic shards 使用并行副本时控制 range 过滤器的设置。值为 0 时将禁用上限"}]}]} />

允许 `range` 类型的过滤器根据自定义范围 `[0, parallel_replicas_custom_key_range_upper]`，在各副本之间均匀拆分工作。值为 0 时将禁用上界，并将其设为自定义键表达式的最大值。

当与 [parallel\_replicas\_custom\_key\_range\_lower](/docs/zh/reference/settings/session-settings/parallel-replicas#parallel_replicas_custom_key_range_lower) 配合使用时，它可让过滤器在范围 `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]` 内将工作均匀分配到各个副本。

注意：此设置不会在查询处理期间额外过滤任何数据；它只是改变了 range 过滤器在并行处理时拆分范围 `[0, INT_MAX]` 的分界点。

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

<BetaBadge />

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

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

允许将过滤器下推到由并行副本选择执行的查询部分

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

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

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

将表函数引擎替换为对应的 -Cluster 版本

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

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

如果为 true，ClickHouse 也会对非复制的 MergeTree 表使用并行副本算法

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.12"},{"label": "1"},{"label": "索引分析仅在副本协调器上执行，其他副本则跳过。仅在启用 parallel_replicas_local_plan 时生效"}]}, {"id": "row-2","items": [{"label": "24.10"},{"label": "1"},{"label": "索引分析仅在副本协调器上执行，其他副本则跳过。仅在启用 parallel_replicas_local_plan 时生效"}]}]} />

索引分析仅在副本协调器上执行，其他副本则跳过。仅在启用 parallel\_replicas\_local\_pla 时生效

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.5"},{"label": "1"},{"label": "在启用并行副本的分布式 INSERT SELECT 中使用本地管道。当前因性能问题已禁用"}]}, {"id": "row-2","items": [{"label": "25.4"},{"label": "0"},{"label": "在启用并行副本的分布式 INSERT SELECT 中使用本地管道。当前因性能问题已禁用"}]}]} />

在启用并行副本的分布式 INSERT SELECT 中使用本地管道

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.9"},{"label": "0"},{"label": "在使用并行副本的查询中，对本地副本使用本地执行计划"}]}, {"id": "row-2","items": [{"label": "24.11"},{"label": "1"},{"label": "在使用并行副本的查询中，对本地副本使用本地执行计划"}]}, {"id": "row-3","items": [{"label": "24.10"},{"label": "1"},{"label": "在使用并行副本的查询中，对本地副本使用本地执行计划"}]}]} />

为本地副本构建本地执行计划

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.9"},{"label": "0"},{"label": "此设置的值现在会自动确定"}]}, {"id": "row-2","items": [{"label": "24.1"},{"label": "128"},{"label": "新增设置，用于在新的并行副本协调器实现中控制分段大小"}]}]} />

parts 会在逻辑上划分为多个分段，以便在并行读取时分配给各个副本。此设置用于控制这些分段的大小。除非你非常确定自己在做什么，否则不建议更改。取值范围应为 \[128; 16384]

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

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

将查询中使用的副本数量限制为 (预计读取的行数 / min\_number\_of\_rows\_per\_replica) 。最大值仍然受 'max\_parallel\_replicas' 限制

<div id="parallel_replicas_mode">
  ## parallel\_replicas\_mode
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "read_tasks"},{"label": "此设置是在将并行副本功能调整为 Beta 的过程中引入的"}]}]} />

并行副本中 custom key 使用的过滤器类型。default - 对 custom key 使用 modulo 运算，range - 在 custom key 上使用 range filter，并基于 custom key 值类型的所有可能值进行处理。

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.2"},{"label": "1"},{"label": "只有在启用 analyzer 时才支持并行副本"}]}]} />

要使用并行副本，必须启用 analyzer。如果 analyzer 被禁用，则查询执行会回退到本地执行，即使已启用从副本进行并行读取也是如此。不支持在未启用 analyzer 的情况下使用并行副本。

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

<ExperimentalBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": "0"},{"label": "新增设置"}]}]} />

将并行副本的本地/远程边界表达为一种执行计划转换。规划器会先构建一个普通的本地执行计划；然后在读取步骤上方插入一个 split 步骤，并将其替换为一个 `UNION`：一部分是本地读取，另一部分是对 split 步骤下方那部分执行计划的远程读取。这样，该 fragment 会在副本上运行，其余部分则在协调器上运行。Experimental，且优先于 `parallel_replicas_local_plan`。

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.2"},{"label": "1"},{"label": "如果为 true，且 JOIN 可以使用并行副本算法执行，并且 JOIN 右侧部分的所有存储引擎均为 *MergeTree，则会使用本地 JOIN，而不是 GLOBAL JOIN。"}]}]} />

如果为 true，且 JOIN 可以使用并行副本算法执行，并且 JOIN 右侧部分的所有存储引擎均为 \*MergeTree，则会使用本地 JOIN，而不是 GLOBAL JOIN。

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.5"},{"label": "1"},{"label": "新设置。禁用后，用于并行读取的副本将完全根据负载均衡算法选择，不会强制将本地副本纳入其中。"}]}]} />

启用时 (默认) ，本地副本始终会包含在用于并行读取的副本集合中。
禁用时，本地副本不再具有任何优先权，副本将完全根据负载均衡算法选择。
这样一来，带有 `max_parallel_replicas = 1` 的查询可被定向到其他主机；当大量短查询分布在集群中时，这有助于改善缓存局部性。

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.8"},{"label": "1"},{"label": "新设置。投影优化可在并行副本中应用。仅在启用 parallel_replicas_local_plan 且 aggregation_in_order 未启用时生效。"}]}]} />

投影优化可在并行副本中应用。仅在启用 parallel\_replicas\_local\_plan 且 aggregation\_in\_order 未启用时生效。