Manage local cache for remote files in Managed ClickHouse®'s tiered storage

Managed ClickHouse®’s tiered storage features local on-disk cache for remote files for improved query performance and reduced latency.

To manage data, Managed ClickHouse’s tiered storage uses local storage and remote storage. When remote storage is used, Managed ClickHouse leverages a local on-disk cache to avoid repeated remote fetches.

How it works

When a query requires parts of a table stored in the remote tier, Managed ClickHouse fetches the required parts from the remote storage. The fetched parts are automatically stored in a local cache directory on the disk to avoid repeated downloads for subsequent queries. For future queries, Managed ClickHouse checks the local cache first:

If the data is found in the cache, it is read directly from the local disk.
If the data is not found in the cache, it is fetched from the remote storage and stored in the local cache.

Local on-disk cache for remote files is enabled by default for Managed ClickHouse’s tiered storage. You can drop it to free up the space it occupies, or disable it per query.

Prerequisites

At least one Managed ClickHouse service using tiered storage
Command line tool (ClickHouse client) installed

Disable the cache

To disable the local cache for a query, set the enable_filesystem_cache setting for the query to false. You can achieve this by appending SETTINGS enable_filesystem_cache = false to the end of your query using an SQL client (for example, the ClickHouse client):

SELECT 1
SETTINGS enable_filesystem_cache = false;

Inspect the cache

Read the current size and entry count of the local cache from system.filesystem_cache:

SELECT
    count() AS entries,
    formatReadableSize(sum(size)) AS cached
FROM system.filesystem_cache

The cache fills as queries read data from the object storage tier, so an empty result simply means nothing has been read from that tier yet.

Free up space

To drop the local cache and free up the used space, use the following cache command:

SYSTEM DROP FILESYSTEM CACHE 'remote_cache'

What’s next

Last updated on August 18, 2026

Manage your Managed ClickHouse® service Manage versions in Managed ClickHouse®