> ## 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_* session settings

> ClickHouse session settings in the distributed_* 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>;
};

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="distributed_aggregation_memory_efficient">
  distributed\_aggregation\_memory\_efficient
</h2>

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

Is the memory-saving mode of distributed aggregation enabled.

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

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

The maximum number of simultaneous connections with remote servers for distributed processing of all queries to a single Distributed table. We recommend setting a value no less than the number of servers in the cluster.

<h2 id="distributed_foreground_insert">
  distributed\_foreground\_insert
</h2>

**Aliases**: `insert_distributed_sync`

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

Enables or disables synchronous data insertion into a [Distributed](/docs/reference/engines/table-engines/special/distributed) table.

By default, when inserting data into a `Distributed` table, the ClickHouse server sends data to cluster nodes in background mode. When `distributed_foreground_insert=1`, the data is processed synchronously, and the `INSERT` operation succeeds only after all the data is saved on all shards (at least one replica for each shard if `internal_replication` is true).

Possible values:

* `0` — Data is inserted in background mode.
* `1` — Data is inserted in synchronous mode.

Cloud default value: `1`.

**See Also**

* [Distributed Table Engine](/docs/reference/engines/table-engines/special/distributed)
* [Managing Distributed Tables](/docs/reference/statements/system#managing-distributed-tables)

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

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

Do not merge aggregation states from different servers for distributed query processing, you can use this in case it is for certain that there are different keys on different shards

Possible values:

* `0` — Disabled (final query processing is done on the initiator node).
* `1` - Do not merge aggregation states from different servers for distributed query processing (query completely processed on the shard, initiator only proxy the data), can be used in case it is for certain that there are different keys on different shards.
* `2` - Same as `1` but applies `ORDER BY` and `LIMIT` (it is not possible when the query processed completely on the remote node, like for `distributed_group_by_no_merge=1`) on the initiator (can be used for queries with `ORDER BY` and/or `LIMIT`).

**Example**

```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 │
└───────┘
```

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "0"},{"label": "If true, INSERT into Distributed will skip read-only replicas"}]}]} />

Enables skipping read-only replicas for INSERT queries into Distributed.

Possible values:

* 0 — INSERT was as usual, if it will go to read-only replica it will fail
* 1 — Initiator will skip read-only replicas before sending data to shards.

<h2 id="distributed_product_mode">
  distributed\_product\_mode
</h2>

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

Changes the behaviour of [distributed subqueries](/docs/reference/statements/in).

ClickHouse applies this setting when the query contains the product of distributed tables, i.e. when the query for a distributed table contains a non-GLOBAL subquery for the distributed table.

Restrictions:

* Only applied for IN and JOIN subqueries.
* Only if the FROM section uses a distributed table containing more than one shard.
* If the subquery concerns a distributed table containing more than one shard.
* Not used for a table-valued [remote](/docs/reference/functions/table-functions/remote) function.

Possible values:

* `deny` — Default value. Prohibits using these types of subqueries (returns the "Double-distributed in/JOIN subqueries is denied" exception).
* `local` — Replaces the database and table in the subquery with local ones for the destination server (shard), leaving the normal `IN`/`JOIN.`
* `global` — Replaces the `IN`/`JOIN` query with `GLOBAL IN`/`GLOBAL JOIN.`
* `allow` — Allows the use of these types of subqueries.

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

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

Enables or disables [LIMIT](/docs/reference/settings/session-settings/other#limit) applying on each shard separately.

This will allow to avoid:

* Sending extra rows over network;
* Processing rows behind the limit on the initiator.

Starting from 21.9 version you cannot get inaccurate results anymore, since `distributed_push_down_limit` changes query execution only if at least one of the conditions met:

* [distributed\_group\_by\_no\_merge](/docs/reference/settings/session-settings/distributed#distributed_group_by_no_merge) > 0.
* Query **does not have** `GROUP BY`/`DISTINCT`/`LIMIT BY`, but it has `ORDER BY`/`LIMIT`.
* Query **has** `GROUP BY`/`DISTINCT`/`LIMIT BY` with `ORDER BY`/`LIMIT` and:
  * [optimize\_skip\_unused\_shards](/docs/reference/settings/session-settings/optimize-skip#optimize_skip_unused_shards) is enabled.
  * [optimize\_distributed\_group\_by\_sharding\_key](/docs/reference/settings/session-settings/optimize#optimize_distributed_group_by_sharding_key) is enabled.

Possible values:

* 0 — Disabled.
* 1 — Enabled.

See also:

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