system.filesystem_cache_settings

​

Description

​

Columns

• cache_name (String) — Cache name
• path (String) — Cache directory path
• max_size (UInt64) — Maximum cache size
• max_elements (UInt64) — Maximum number of cache elements, e.g. file segments (limits number of files on filesystem)
• max_file_segment_size (UInt64) — Maximum size of a single file segment
• boundary_alignment (UInt64) — File segment alignment
• reserve_granularity (UInt64) — Maximum size to reserve ahead of the downloaded size of a file segment, to take the cache lock less often. Starts from 0 for each reader/writer and grows with its repeated reservations up to this value. 0 disables reserve-ahead.
• cache_on_write_operations (UInt8) — Enables write-through cache (cache on INSERT and MERGE)
• cache_policy (String) — Cache eviction policy
• slru_size_ratio (Float64) — SLRU cache policy size ratio of protected to probationary elements
• background_download_threads (UInt64) — Number of background download threads. Value 0 disables background download
• background_download_queue_size_limit (UInt64) — Maximum number of file segments in the background download queue. Value 0 means no limit. Background download is disabled when background_download_threads is 0
• background_download_max_file_segment_size (UInt64) — Alignment-rounded prefetch threshold for an already-started segment, not a cap on total segment size. Below this size, background download fills up to the value rounded up to boundary_alignment. Once downloaded_size reaches it, background download continues up to downloaded_size rounded up to boundary_alignment
• load_metadata_threads (UInt64) — Maximum number of threads used to load cache metadata at server startup
• load_metadata_asynchronously (UInt8) — Enables asynchronous loading of metadata on server startup
• keep_free_space_size_ratio (Float64) — A ratio of free space which cache would try to uphold in the background
• keep_free_space_elements_ratio (Float64) — A ratio of free elements which cache would try to uphold in the background
• keep_free_space_remove_batch (UInt64) — A remove batch size of cache elements made by background thread which upholds free space/elements ratio
• keep_free_space_eviction_threads (UInt64) — Number of threads which perform the actual file segment removal (filesystem deletion) for the background free space/elements ratio keeping. The single background thread collects eviction candidates and frees their priority queue entries, while these threads do the lock-free removal in parallel
• invalidated_entries_cleanup_interval_ms (UInt64) — Idle interval in milliseconds of the background task which purges invalidated (lazily-removed) priority queue entries
• invalidated_entries_cleanup_threshold (UInt64) — Number of accumulated invalidated priority queue entries which triggers their background removal
• invalidated_entries_cleanup_remove_batch (UInt64) — Maximum number of invalidated priority queue entries removed under a single write lock per background iteration
• enable_filesystem_query_cache_limit (UInt8) — Enable limiting maximum size of cache which can be written within a query
• cache_hits_threshold (UInt64) — Deprecated setting
• enable_bypass_cache_with_threshold (UInt8) — Undocumented. Not recommended for use
• bypass_cache_threshold (UInt64) — Undocumented. Not recommended for use
• write_cache_per_user_id_directory (UInt8) — Deprecated setting, ignored. The behavior is now determined automatically based on cache policy
• allow_dynamic_cache_resize (UInt8) — Allow dynamic resize of filesystem cache
• dynamic_resize_lock_wait_ms (UInt64) — Timeout in milliseconds to acquire the dynamic resize exclusive lock before skipping the resize attempt
• max_size_ratio_to_total_space (Float64) — Ratio of max_size to total disk space
• skip_cache_on_disk_failure (UInt8) — If true, bypass filesystem cache operations silently on disk IO errors. If false (default), disk IO errors are propagated as startup failures.
• use_split_cache (UInt8) — Use separation of files to system/data.
• split_cache_ratio (Float64) — Ratio of system segment to total size of cache for split_cache.
• system_cache_extensions (String) — Comma-separated list of file extensions that are classified as system cache segments when use_split_cache is enabled. When changed, existing cache entries remain in their previous segment type and are evicted naturally over time. Restart is required to change this setting.
• overcommit_eviction_evict_step (UInt64) — Eviction step in bytes for overcommit eviction policy. Used for keep_free_space_*_ratio settings
• check_cache_probability (Float64) — Works only for debug or sanitizer build. Checks cache correctness by going through all cache and checking state of each cache element
• idle_client_ttl_sec (UInt64) — If non-zero and the cache policy tracks per-client usage, all cache entries that belong to a client (user_id) which has not been accessed for this many seconds are fully removed from the cache. Each access by the client refreshes the timer. Default is 1 week. Used by the distributed cache server.
• idle_client_check_interval_sec (UInt64) — How often the idle client eviction task runs, in seconds. Only meaningful when idle_client_ttl_sec is non-zero. 0 means an automatic value (max(1, idle_client_ttl_sec / 10)).
• idle_client_eviction_threads (UInt64) — Maximum number of threads used to purge idle clients’ cache. Only meaningful when idle_client_ttl_sec is non-zero.
• expose_prometheus_eviction_metrics (UInt8) — Expose Prometheus metrics for filesystem cache eviction activity (filesystem_cache_evictions_total etc.). Off by default. Can be toggled at runtime via SYSTEM RELOAD CONFIG.
• expose_prometheus_eviction_metrics_per_user (UInt8) — Additionally expose per-user-id eviction metrics. Requires expose_prometheus_eviction_metrics. Cardinality grows with distinct evicting users.
• drop_cache_threads (UInt64) — Maximum number of threads used to remove cache keys in parallel on SYSTEM DROP FILESYSTEM CACHE. Value 1 means the removal is performed by the query thread alone
• is_initialized (UInt8) — Indicates whether cache was successfully initialized
• current_size (UInt64) — Current cache size
• current_elements_num (UInt64) — Current cache elements (file segments) number