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

> ClickHouse session settings in the distributed_background_* 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_background_insert_batch">
  distributed\_background\_insert\_batch
</h2>

**Aliases**: `distributed_directory_monitor_batch_inserts`

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

Enables/disables inserted data sending in batches.

When batch sending is enabled, the [Distributed](/docs/reference/engines/table-engines/special/distributed) table engine tries to send multiple files of inserted data in one operation instead of sending them separately. Batch sending improves cluster performance by better-utilizing server and network resources.

Possible values:

* 1 — Enabled.
* 0 — Disabled.

<h2 id="distributed_background_insert_max_sleep_time_ms">
  distributed\_background\_insert\_max\_sleep\_time\_ms
</h2>

**Aliases**: `distributed_directory_monitor_max_sleep_time_ms`

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

Maximum interval for the [Distributed](/docs/reference/engines/table-engines/special/distributed) table engine to send data. Limits exponential growth of the interval set in the [distributed\_background\_insert\_sleep\_time\_ms](/docs/reference/settings/session-settings/distributed-background#distributed_background_insert_sleep_time_ms) setting.

Possible values:

* A positive integer number of milliseconds.

<h2 id="distributed_background_insert_sleep_time_ms">
  distributed\_background\_insert\_sleep\_time\_ms
</h2>

**Aliases**: `distributed_directory_monitor_sleep_time_ms`

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

Base interval for the [Distributed](/docs/reference/engines/table-engines/special/distributed) table engine to send data. The actual interval grows exponentially in the event of errors.

Possible values:

* A positive integer number of milliseconds.

<h2 id="distributed_background_insert_split_batch_on_failure">
  distributed\_background\_insert\_split\_batch\_on\_failure
</h2>

**Aliases**: `distributed_directory_monitor_split_batch_on_failure`

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

Enables/disables splitting batches on failures.

Sometimes sending particular batch to the remote shard may fail, because of some complex pipeline after (i.e. `MATERIALIZED VIEW` with `GROUP BY`) due to `Memory limit exceeded` or similar errors. In this case, retrying will not help (and this will stuck distributed sends for the table) but sending files from that batch one by one may succeed INSERT.

So installing this setting to `1` will disable batching for such batches (i.e. temporary disables `distributed_background_insert_batch` for failed batches).

Possible values:

* 1 — Enabled.
* 0 — Disabled.

<Note>
  This setting also affects broken batches (that may appears because of abnormal server (machine) termination and no `fsync_after_insert`/`fsync_directories` for [Distributed](/docs/reference/engines/table-engines/special/distributed) table engine).
</Note>

<Note>
  You should not rely on automatic batch splitting, since this may hurt performance.
</Note>

<h2 id="distributed_background_insert_timeout">
  distributed\_background\_insert\_timeout
</h2>

**Aliases**: `insert_distributed_timeout`

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

Timeout for insert query into distributed. Setting is used only with insert\_distributed\_sync enabled. Zero value means no timeout.