> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# filesystem_cache_* 会话设置

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

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

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["版本", "默认值", "注释"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        版本历史
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

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](/zh/reference/system-tables/settings) 中找到，并由 [源代码](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) 自动生成。

<div id="filesystem_cache_allow_background_download">
  ## filesystem\_cache\_allow\_background\_download
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.11"},{"label": "1"},{"label": "用于控制文件系统缓存按查询在后台下载的新设置。"}]}]} />

允许文件系统缓存将从远程存储读取的数据加入后台下载队列。禁用后，当前查询/会话的下载将改为在前台进行。

<div id="filesystem_cache_boundary_alignment">
  ## filesystem\_cache\_boundary\_alignment
</div>

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

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

文件系统缓存边界对齐。此设置仅适用于非磁盘读取 (例如远程表引擎 / 表函数的缓存，不适用于 MergeTree 表的存储配置) 。值 0 表示不进行对齐。

<div id="filesystem_cache_enable_background_download_during_fetch">
  ## filesystem\_cache\_enable\_background\_download\_during\_fetch
</div>

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中生效。锁定缓存的等待时间

<div id="filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage">
  ## filesystem\_cache\_enable\_background\_download\_for\_metadata\_files\_in\_packed\_storage
</div>

<CloudOnlyBadge />

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

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

仅在 ClickHouse Cloud 中有效。锁定缓存的等待时间

<div id="filesystem_cache_max_download_size">
  ## filesystem\_cache\_max\_download\_size
</div>

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

单个查询可下载的远程文件系统缓存的最大大小

<div id="filesystem_cache_name">
  ## filesystem\_cache\_name
</div>

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": ""},{"label": "用于无状态表引擎或数据湖的文件系统缓存名称"}]}]} />

用于无状态表引擎或数据湖的文件系统缓存名称

<div id="filesystem_cache_prefer_bigger_buffer_size">
  ## filesystem\_cache\_prefer\_bigger\_buffer\_size
</div>

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

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

如果启用了文件系统缓存，则优先使用更大的缓冲区，以避免写入较小的 File 段，从而导致缓存性能下降。另一方面，启用此设置可能会增加内存占用。

<div id="filesystem_cache_reserve_space_wait_lock_timeout_milliseconds">
  ## filesystem\_cache\_reserve\_space\_wait\_lock\_timeout\_milliseconds
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "1000"},{"label": "为文件系统缓存预留空间时锁定缓存的等待时间"}]}]} />

为文件系统缓存预留空间时锁定缓存的等待时间

<div id="filesystem_cache_segments_batch_size">
  ## filesystem\_cache\_segments\_batch\_size
</div>

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

读取缓冲区一次可向缓存请求的单个 File 段批次大小上限。值过低会导致向缓存发起过多请求，值过高则可能减慢缓存逐出

<div id="filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit">
  ## filesystem\_cache\_skip\_download\_if\_exceeds\_per\_query\_cache\_write\_limit
</div>

**别名**: `skip_download_if_exceeds_query_cache`

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "1"},{"label": "设置 skip_download_if_exceeds_query_cache_limit 的重命名"}]}]} />

如果会超过查询缓存大小，则跳过从远程文件系统下载

<div id="filesystem_cache_verbose_logging">
  ## filesystem\_cache\_verbose\_logging
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "0"},{"label": "新增设置，用于控制文件系统缓存读取缓冲区每次重新填充时的 TEST 级别日志消息；此前，只要日志级别允许，就会无条件发出这些消息。"}]}]} />

每次重新填充文件系统缓存缓冲区时，发出 `TEST` 级别的日志消息 (读取状态、剩余待读取大小、已读取字节数) 。仅用于调试：每次读取时都会格式化这些消息，因此，对执行大量小规模缓存读取的查询启用此设置会显著增加日志开销。无论如何，这些消息仅在日志级别为 `test` 时可见 (请参阅 `send_logs_level`) 。

<div id="filesystem_cache_wait_for_concurrent_download_timeout_milliseconds">
  ## filesystem\_cache\_wait\_for\_concurrent\_download\_timeout\_milliseconds
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "1000"},{"label": "用于限制读取等待并发查询将 File 段下载至文件系统缓存所需时长的新设置；超时后，读取将绕过缓存，而不会无限期等待。先前的值 60000 对应旧行为（在下载器上完成一次完整的 60 秒等待周期）。"}]}]} />

等待并发查询下载至文件系统缓存的 File 段的最长时间。达到超时时间后，读取会绕过该范围的文件系统缓存，直接从远程存储读取；同时，并发下载会继续填充缓存。值 `0` 表示完全不等待：如果所需范围尚未下载，则立即绕过缓存。降低此值可限制原本会按另一查询下载进度等待的缓存命中读取的尾延迟，但会增加对远程存储的请求。