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

# distributed_* 会话设置

> ClickHouse 在 distributed_* 自动生成分组中的会话设置。

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>;
};

这些设置可在 [system.settings](/docs/zh/reference/system-tables/settings) 中找到，并根据 [源代码](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) 自动生成。

<div id="distributed_aggregation_memory_efficient">
  ## distributed\_aggregation\_memory\_efficient
</div>

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

是否启用分布式聚合的内存节省模式。

<div id="distributed_connections_pool_size">
  ## distributed\_connections\_pool\_size
</div>

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

对单个 Distributed 表的所有查询执行分布式处理时，与远程服务器的最大并发连接数。建议将该值设置为不小于集群中的服务器数量。

<div id="distributed_foreground_insert">
  ## distributed\_foreground\_insert
</div>

**别名**: `insert_distributed_sync`

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

启用或禁用向 [Distributed](/docs/zh/reference/engines/table-engines/special/distributed) 表同步插入数据。

默认情况下，向 `Distributed` 表插入数据时，ClickHouse server 会以后台模式将数据发送到集群节点。当 `distributed_foreground_insert=1` 时，数据会同步处理，并且只有在所有数据都保存到所有分片上之后，`INSERT` 操作才会成功 (如果 `internal_replication` 为 true，则每个分片上至少有一个副本) 。

可能的值：

* `0` — 数据以后台模式插入。
* `1` — 数据以同步模式插入。

Cloud 默认值：`1`。

**另请参见**

* [Distributed 表引擎](/docs/zh/reference/engines/table-engines/special/distributed)
* [管理分布式表](/docs/zh/reference/statements/system#managing-distributed-tables)

<div id="distributed_group_by_no_merge">
  ## distributed\_group\_by\_no\_merge
</div>

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

在分布式查询处理过程中，不合并来自不同服务器的聚合状态；当可以确定不同分片上的键各不相同时，可使用此设置

可能的值：

* `0` — 禁用 (最终查询处理在发起节点上完成) 。
* `1` - 在分布式查询处理过程中，不合并来自不同服务器的聚合状态 (查询在分片上完全处理，发起节点仅转发数据) ；当可以确定不同分片上的键各不相同时，可使用此设置。
* `2` - 与 `1` 相同，但会在发起节点上应用 `ORDER BY` 和 `LIMIT` (而在 `distributed_group_by_no_merge=1` 的情况下，当查询完全在远程节点上处理时，这是不可能的)  (可用于带有 `ORDER BY` 和/或 `LIMIT` 的查询) 。

**示例**

```sql theme={null}
SELECT *
FROM remote('127.0.0.{2,3}', system.one)
GROUP BY dummy
LIMIT 1
SETTINGS distributed_group_by_no_merge = 1
FORMAT PrettyCompactMonoBlock

┌─dummy─┐
│     0 │
│     0 │
└───────┘
```

```sql theme={null}
SELECT *
FROM remote('127.0.0.{2,3}', system.one)
GROUP BY dummy
LIMIT 1
SETTINGS distributed_group_by_no_merge = 2
FORMAT PrettyCompactMonoBlock

┌─dummy─┐
│     0 │
└───────┘
```

<div id="distributed_insert_skip_read_only_replicas">
  ## distributed\_insert\_skip\_read\_only\_replicas
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "0"},{"label": "如果为 true，则向 Distributed 执行 INSERT 时会跳过只读副本"}]}]} />

启用后，对于向 Distributed 执行的 INSERT 查询，会跳过只读副本。

可选值：

* 0 — INSERT 行为保持不变；如果请求发送到只读副本，将会失败
* 1 — 发起节点会在将数据发送到分片之前跳过只读副本。

<div id="distributed_product_mode">
  ## distributed\_product\_mode
</div>

<SettingsInfoBlock type="DistributedProductMode" default_value="deny" />

更改[分布式子查询](/docs/zh/reference/statements/in)的行为。

当查询中出现分布式表的乘积时，ClickHouse 会应用此设置；也就是说，当针对分布式表的查询中包含一个针对该分布式表的非 GLOBAL 子查询时，就会应用此设置。

限制：

* 仅适用于 IN 和 JOIN 子查询。
* 仅当 FROM 子句使用了包含多个分片的分布式表时。
* 仅当子查询涉及包含多个分片的分布式表时。
* 不适用于表值函数 [remote](/docs/zh/reference/functions/table-functions/remote)。

可能的值：

* `deny` — 默认值。禁止使用这类子查询 (返回 “Double-distributed in/JOIN subqueries is denied” 异常) 。
* `local` — 将子查询中的数据库和表替换为目标端服务器 (分片) 的本地数据库和表，保留普通的 `IN`/`JOIN.`
* `global` — 将 `IN`/`JOIN` 查询替换为 `GLOBAL IN`/`GLOBAL JOIN.`
* `allow` — 允许使用这类子查询。

<div id="distributed_push_down_limit">
  ## distributed\_push\_down\_limit
</div>

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

启用或禁用在每个分片上单独应用 [LIMIT](/docs/zh/reference/settings/session-settings/other#limit)。

这样可以避免：

* 通过网络传输多余的行；
* 在发起节点上处理超出 LIMIT 的行。

从 21.9 版本开始，将不再出现结果不准确的情况，因为 `distributed_push_down_limit` 只有在至少满足以下条件之一时才会更改查询执行：

* [distributed\_group\_by\_no\_merge](/docs/zh/reference/settings/session-settings/distributed#distributed_group_by_no_merge) > 0。
* 查询**不包含** `GROUP BY`/`DISTINCT`/`LIMIT BY`，但包含 `ORDER BY`/`LIMIT`。
* 查询**包含** `GROUP BY`/`DISTINCT`/`LIMIT BY` 以及 `ORDER BY`/`LIMIT`，并且：
  * [optimize\_skip\_unused\_shards](/docs/zh/reference/settings/session-settings/optimize-skip#optimize_skip_unused_shards) 已启用。
  * [optimize\_distributed\_group\_by\_sharding\_key](/docs/zh/reference/settings/session-settings/optimize#optimize_distributed_group_by_sharding_key) 已启用。

可能的值：

* 0 — 禁用。
* 1 — 启用。

另请参见：

* [distributed\_group\_by\_no\_merge](/docs/zh/reference/settings/session-settings/distributed#distributed_group_by_no_merge)
* [optimize\_skip\_unused\_shards](/docs/zh/reference/settings/session-settings/optimize-skip#optimize_skip_unused_shards)
* [optimize\_distributed\_group\_by\_sharding\_key](/docs/zh/reference/settings/session-settings/optimize#optimize_distributed_group_by_sharding_key)