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

> ClickHouse session settings in the distributed_cache_* 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 CloudOnlyBadge = () => {
  return <div className="cloudBadge">
            <div className="cloudIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path fillRule="evenodd" clipRule="evenodd" d="M5.33395 12.6667H12.3739C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00004 12.3739 8.00004H12.0839V7.33337C12.0839 5.12671 10.2906 3.33337 8.08395 3.33337C6.09928 3.33337 4.45395 4.78537 4.14195 6.68204C2.55728 6.76271 1.29395 8.06204 1.29395 9.66671C1.29395 11.3234 2.63728 12.6667 4.29395 12.6667H5.33395Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'ClickHouse Cloud only'}
        </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_cache_alignment">
  distributed\_cache\_alignment
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.7"},{"label": "0"},{"label": "Rename of distributed_cache_read_alignment"}]}]} />

Only has an effect in ClickHouse Cloud. A setting for testing purposes, do not change it

<h2 id="distributed_cache_bypass_connection_pool">
  distributed\_cache\_bypass\_connection\_pool
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "0"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Allow to bypass distributed cache connection pool

<h2 id="distributed_cache_connect_backoff_max_ms">
  distributed\_cache\_connect\_backoff\_max\_ms
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Maximum backoff milliseconds for distributed cache connection creation.

<h2 id="distributed_cache_connect_backoff_min_ms">
  distributed\_cache\_connect\_backoff\_min\_ms
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Minimum backoff milliseconds for distributed cache connection creation.

<h2 id="distributed_cache_connect_max_tries">
  distributed\_cache\_connect\_max\_tries
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.8"},{"label": "5"},{"label": "Changed setting value"}]}, {"id": "row-2","items": [{"label": "25.1"},{"label": "20"},{"label": "Cloud only"}]}, {"id": "row-3","items": [{"label": "24.10"},{"label": "20"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Number of tries to connect to distributed cache if unsuccessful

<h2 id="distributed_cache_connect_timeout_ms">
  distributed\_cache\_connect\_timeout\_ms
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Connection timeout when connecting to distributed cache server.

<h2 id="distributed_cache_credentials_refresh_period_seconds">
  distributed\_cache\_credentials\_refresh\_period\_seconds
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. A period of credentials refresh.

<h2 id="distributed_cache_data_packet_ack_window">
  distributed\_cache\_data\_packet\_ack\_window
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "5"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. A window for sending ACK for DataPacket sequence in a single distributed cache read request

<h2 id="distributed_cache_discard_connection_if_unread_data">
  distributed\_cache\_discard\_connection\_if\_unread\_data
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Discard connection if some data is unread.

<h2 id="distributed_cache_fetch_metrics_only_from_current_az">
  distributed\_cache\_fetch\_metrics\_only\_from\_current\_az
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "1"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Fetch metrics only from current availability zone in system.distributed\_cache\_metrics, system.distributed\_cache\_events

<h2 id="distributed_cache_file_cache_name">
  distributed\_cache\_file\_cache\_name
</h2>

<CloudOnlyBadge />

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

Only has an effect in ClickHouse Cloud. A setting used only for CI tests - filesystem cache name to use on distributed cache.

<h2 id="distributed_cache_log_mode">
  distributed\_cache\_log\_mode
</h2>

<CloudOnlyBadge />

<SettingsInfoBlock type="DistributedCacheLogMode" default_value="on_error" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "on_error"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Mode for writing to system.distributed\_cache\_log

<h2 id="distributed_cache_max_unacked_inflight_packets">
  distributed\_cache\_max\_unacked\_inflight\_packets
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "10"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. A maximum number of unacknowledged in-flight packets in a single distributed cache read request

<h2 id="distributed_cache_min_bytes_for_seek">
  distributed\_cache\_min\_bytes\_for\_seek
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Minimum number of bytes to do seek in distributed cache.

<h2 id="distributed_cache_pool_behaviour_on_limit">
  distributed\_cache\_pool\_behaviour\_on\_limit
</h2>

<CloudOnlyBadge />

<SettingsInfoBlock type="DistributedCachePoolBehaviourOnLimit" default_value="wait" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.1"},{"label": "wait"},{"label": "Cloud only"}]}, {"id": "row-2","items": [{"label": "24.10"},{"label": "allocate_bypassing_pool"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Identifies behaviour of distributed cache connection on pool limit reached

<h2 id="distributed_cache_prefer_bigger_buffer_size">
  distributed\_cache\_prefer\_bigger\_buffer\_size
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Same as filesystem\_cache\_prefer\_bigger\_buffer\_size, but for distributed cache.

<h2 id="distributed_cache_read_only_from_current_az">
  distributed\_cache\_read\_only\_from\_current\_az
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Allow to read only from current availability zone. If disabled, will read from all cache servers in all availability zones.

<h2 id="distributed_cache_read_request_max_tries">
  distributed\_cache\_read\_request\_max\_tries
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.8"},{"label": "10"},{"label": "Changed setting value"}]}, {"id": "row-2","items": [{"label": "25.4"},{"label": "20"},{"label": "New setting"}]}]} />

Only has an effect in ClickHouse Cloud. Number of tries to do distributed cache read request if unsuccessful

<h2 id="distributed_cache_receive_response_wait_milliseconds">
  distributed\_cache\_receive\_response\_wait\_milliseconds
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "60000"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Wait time in milliseconds to receive data for request from distributed cache

<h2 id="distributed_cache_receive_timeout_milliseconds">
  distributed\_cache\_receive\_timeout\_milliseconds
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "10000"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Wait time in milliseconds to receive any kind of response from distributed cache

Cloud default value: `20000`.

<h2 id="distributed_cache_receive_timeout_ms">
  distributed\_cache\_receive\_timeout\_ms
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Timeout for receiving data from distributed cache server, in milliseconds. If no bytes were received in this interval, the exception is thrown.

<h2 id="distributed_cache_registry_show_certificate_and_signature">
  distributed\_cache\_registry\_show\_certificate\_and\_signature
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.6"},{"label": "0"},{"label": "New setting to show the `certificate` and `signature` columns in `system.distributed_cache_registry`."}]}]} />

Only has an effect in ClickHouse Cloud. Show the `certificate` and `signature` columns in the `system.distributed_cache_registry` table. By default these columns are empty to keep the output compact; enable this setting to inspect them.

<h2 id="distributed_cache_send_timeout_ms">
  distributed\_cache\_send\_timeout\_ms
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Timeout for sending data to istributed cache server, in milliseconds. If a client needs to send some data but is not able to send any bytes in this interval, the exception is thrown.

<h2 id="distributed_cache_tcp_keep_alive_timeout_ms">
  distributed\_cache\_tcp\_keep\_alive\_timeout\_ms
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. The time in milliseconds the connection to distributed cache server needs to remain idle before TCP starts sending keepalive probes.

<h2 id="distributed_cache_throw_on_error">
  distributed\_cache\_throw\_on\_error
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "0"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Rethrow exception happened during communication with distributed cache or exception received from distributed cache. Otherwise fallback to skipping distributed cache on error

<h2 id="distributed_cache_use_clients_cache_for_read">
  distributed\_cache\_use\_clients\_cache\_for\_read
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Use clients cache for read requests.

<h2 id="distributed_cache_wait_connection_from_pool_milliseconds">
  distributed\_cache\_wait\_connection\_from\_pool\_milliseconds
</h2>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "100"},{"label": "A setting for ClickHouse Cloud"}]}]} />

Only has an effect in ClickHouse Cloud. Wait time in milliseconds to receive connection from connection pool if distributed\_cache\_pool\_behaviour\_on\_limit is wait

<h2 id="distributed_cache_write_request_max_tries">
  distributed\_cache\_write\_request\_max\_tries
</h2>

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Number of tries to do distributed cache write request if unsuccessful