External disks for storing data

Example of configuration for versions later or equal to 22.8:

```
<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
            </s3>
            <cache>
                <type>cache</type>
                <disk>s3</disk>
                <path>/s3_cache/</path>
                <max_size>10Gi</max_size>
            </cache>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>cache</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>
```

Example of configuration for versions earlier than 22.8:

```
<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
                <data_cache_enabled>1</data_cache_enabled>
                <data_cache_max_size>10737418240</data_cache_max_size>
            </s3>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>
```

File Cache **disk configuration settings**:

These settings should be defined in the disk configuration section.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `path` String - **Required**. Path to the directory where cache will be stored.| `max_size` Size - **Required**. Maximum cache size in bytes or readable format (e.g., `10Gi`). Files are evicted using LRU policy when the limit is reached. Supports `ki`, `Mi`, `Gi` formats (since v22.10).| `cache_on_write_operations` Boolean `false` Enables write-through cache for `INSERT` queries and background merges. Can be overridden per query with `enable_filesystem_cache_on_write_operations`.| `enable_filesystem_query_cache_limit` Boolean `false` Enables per-query cache size limits based on `max_query_cache_size`.| `enable_cache_hits_threshold` Boolean `false` When enabled, data is cached only after being read multiple times.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `cache_hits_threshold` Integer `0` Number of reads required before data is cached (requires `enable_cache_hits_threshold`).| `enable_bypass_cache_with_threshold` Boolean `false` Skips cache for large read ranges.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `bypass_cache_threshold` Size `256Mi` Read range size that triggers cache bypass (requires `enable_bypass_cache_with_threshold`).| `max_file_segment_size` Size `8Mi` Maximum size of a single cache file in bytes or readable format.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `max_elements` Integer `10000000` Maximum number of cache files.|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `load_metadata_threads` Integer `16` Number of threads for loading cache metadata at startup.|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `use_split_cache` Boolean `false` Use separation of files to system/data.|  |  |  |  | | --- | --- | --- | --- | | `split_cache_ratio` Double `0.1` Ratio of system segment to total size of cache for split\_cache. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

> **Note**: Size values support units like `ki`, `Mi`, `Gi`, etc. (e.g., `10Gi`).

## File Cache Query/Profile Settings[​](#file-cache-query-profile-settings "Direct link to File Cache Query/Profile Settings")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Type Default Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `enable_filesystem_cache` Boolean `true` Enables/disables cache usage per query, even when using a `cache` disk type.| `read_from_filesystem_cache_if_exists_otherwise_bypass_cache` Boolean `false` When enabled, uses cache only if data exists; new data won't be cached.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `enable_filesystem_cache_on_write_operations` Boolean `false` (Cloud: `true`) Enables write-through cache. Requires `cache_on_write_operations` in cache config.| `enable_filesystem_cache_log` Boolean `false` Enables detailed cache usage logging to `system.filesystem_cache_log`.| `filesystem_cache_allow_background_download` Boolean `true` Allows partially downloaded segments to be finished in the background. Disable to keep downloads in the foreground for the current query/session.|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `max_query_cache_size` Size `false` Maximum cache size per query. Requires `enable_filesystem_query_cache_limit` in cache config.| `filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit` Boolean `true` Controls behavior when `max_query_cache_size` is reached:  - `true`: Stops downloading new data  - `false`: Evicts old data to make space for new data | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Note

Cache configuration settings and cache query settings correspond to the latest ClickHouse version,
for earlier versions something might not be supported.

#### Cache system tables[​](#cache-system-tables-file-cache "Direct link to Cache system tables")

|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Table Name Description Requirements|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `system.filesystem_cache` Displays the current state of the filesystem cache. None|  |  |  | | --- | --- | --- | | `system.filesystem_cache_log` Provides detailed cache usage statistics per query. Requires `enable_filesystem_cache_log = true` | | | | | | | | |

#### Cache commands[​](#cache-commands-file-cache "Direct link to Cache commands")