> ## 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.

# filesystem_cache_* session settings

> ClickHouse session settings in the filesystem_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="filesystem_cache_allow_background_download">
  filesystem\_cache\_allow\_background\_download
</h2>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.11"},{"label": "1"},{"label": "New setting to control background downloads in filesystem cache per query."}]}]} />

Allow filesystem cache to enqueue background downloads for data read from remote storage. Disable to keep downloads in the foreground for the current query/session.

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

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

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

Filesystem cache boundary alignment. This setting is applied only for non-disk read (e.g. for cache of remote table engines / table functions, but not for storage configuration of MergeTree tables). Value 0 means no alignment.

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

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Wait time to lock cache for space reservation in filesystem cache

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

<CloudOnlyBadge />

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

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

Only has an effect in ClickHouse Cloud. Wait time to lock cache for space reservation in filesystem cache

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

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

Max remote filesystem cache size that can be downloaded by a single query

<h2 id="filesystem_cache_name">
  filesystem\_cache\_name
</h2>

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": ""},{"label": "Filesystem cache name to use for stateless table engines or data lakes"}]}]} />

Filesystem cache name to use for stateless table engines or data lakes

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

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

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

Prefer bigger buffer size if filesystem cache is enabled to avoid writing small file segments which deteriorate cache performance. On the other hand, enabling this setting might increase memory usage.

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

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "1000"},{"label": "Wait time to lock cache for space reservation in filesystem cache"}]}]} />

Wait time to lock cache for space reservation in filesystem cache

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

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

Limit on size of a single batch of file segments that a read buffer can request from cache. Too low value will lead to excessive requests to cache, too large may slow down eviction from cache

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

**Aliases**: `skip_download_if_exceeds_query_cache`

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "1"},{"label": "Rename of setting skip_download_if_exceeds_query_cache_limit"}]}]} />

Skip download from remote filesystem if exceeds query cache size