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

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

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 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'}
        </div>;
};

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

<div id="distributed_cache_alignment">
  ## distributed\_cache\_alignment
</div>

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.7"},{"label": "0"},{"label": "由 distributed_cache_read_alignment 重命名而来"}]}]} />

仅在 ClickHouse Cloud 中生效。此设置仅用于测试，请勿更改

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "0"},{"label": "适用于 ClickHouse Cloud 的设置"}]}]} />

仅在 ClickHouse Cloud 中生效。允许绕过分布式缓存连接池。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。分布式缓存创建连接时的最大退避毫秒数。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。分布式缓存创建连接时的最小退避毫秒数。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.8"},{"label": "5"},{"label": "设置值已更改"}]}, {"id": "row-2","items": [{"label": "25.1"},{"label": "20"},{"label": "仅限 Cloud"}]}, {"id": "row-3","items": [{"label": "24.10"},{"label": "20"},{"label": "ClickHouse Cloud 专用设置"}]}]} />

仅在 ClickHouse Cloud 中生效。连接分布式缓存失败时的重试次数

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。连接到 Distributed Cache 服务器时的连接超时。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.6"},{"label": "5"},{"label": "新增私有设置"}]}]} />

仅在 ClickHouse Cloud 中生效。凭证刷新周期。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "5"},{"label": "ClickHouse Cloud 的设置项"}]}]} />

仅在 ClickHouse Cloud 中生效。用于在单个分布式缓存读取请求中为 DataPacket 序列发送 ACK 的窗口大小

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。如果存在未读取的数据，则断开连接。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "1"},{"label": "ClickHouse Cloud 专用设置"}]}]} />

仅在 ClickHouse Cloud 中生效。在 system.distributed\_cache\_metrics 和 system.distributed\_cache\_events 中，仅从当前可用区拉取指标。

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

<CloudOnlyBadge />

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

仅在 ClickHouse Cloud 中生效。此设置仅用于 CI 测试，用于指定分布式缓存使用的文件系统缓存名称。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "on_error"},{"label": "ClickHouse Cloud 设置项"}]}]} />

仅在 ClickHouse Cloud 中生效。用于写入 system.distributed\_cache\_log 的模式

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "10"},{"label": "ClickHouse Cloud 设置项"}]}]} />

仅在 ClickHouse Cloud 中生效。单个分布式缓存读取请求中处于传输中的未确认数据包的最大数量

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。分布式缓存中执行寻道的最小字节数。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.1"},{"label": "wait"},{"label": "仅限 Cloud"}]}, {"id": "row-2","items": [{"label": "24.10"},{"label": "allocate_bypassing_pool"},{"label": "适用于 ClickHouse Cloud 的设置"}]}]} />

仅在 ClickHouse Cloud 中生效。用于指定分布式缓存连接在达到连接池限制时的行为

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中有效。与 filesystem\_cache\_prefer\_bigger\_buffer\_size 相同，但适用于分布式缓存。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。允许只从当前可用区读取数据。若禁用，则会从所有可用区中的所有缓存服务器读取。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.8"},{"label": "10"},{"label": "设置值已变更"}]}, {"id": "row-2","items": [{"label": "25.4"},{"label": "20"},{"label": "新设置"}]}]} />

仅在 ClickHouse Cloud 中生效。分布式缓存读取请求失败时的最大重试次数

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "60000"},{"label": "ClickHouse Cloud 设置项"}]}]} />

仅在 ClickHouse Cloud 中生效。从分布式缓存接收请求数据的等待时间 (毫秒) 。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "10000"},{"label": "ClickHouse Cloud 设置项"}]}]} />

仅在 ClickHouse Cloud 中生效。以毫秒为单位，表示从分布式缓存接收任意类型响应的等待时间。

Cloud 默认值：`20000`。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。该设置表示从 Distributed Cache 服务器接收数据的超时时间，单位为毫秒。如果在此时间间隔内未接收到任何字节，则会抛出异常。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.6"},{"label": "0"},{"label": "用于在 `system.distributed_cache_registry` 中显示 `certificate` 和 `signature` 列的新设置。"}]}]} />

仅在 ClickHouse Cloud 中生效。显示 `system.distributed_cache_registry` 表中的 `certificate` 和 `signature` 列。默认情况下，这些列为空，以保持输出简洁；启用此设置可查看其内容。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。向 Distributed Cache 服务器发送数据的超时时间，单位为毫秒。如果客户端需要发送数据，但在此时间间隔内无法发送任何字节，则会抛出异常。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。该值表示在 TCP 开始发送 keepalive 探测之前，与 Distributed Cache 服务器的连接需保持空闲的时间 (毫秒) 。

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

<CloudOnlyBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "0"},{"label": "ClickHouse Cloud 的一项设置"}]}]} />

仅在 ClickHouse Cloud 中生效。若在与分布式缓存通信期间发生异常，或收到来自分布式缓存的异常，则重新抛出该异常。否则，出错时回退为跳过分布式缓存。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。对读取请求使用 clients cache。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。当 distributed\_cache\_pool\_behaviour\_on\_limit 为 wait 时，表示从连接池中获取连接的等待时间，单位为毫秒。

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

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。分布式缓存写入请求失败时的重试次数