Ben Kimpel
05/10/2026, 3:44 PMRocky
05/10/2026, 3:44 PMenable_datacache_async_populate_mode
From v3.3.0 onwards, StarRocks enables asynchronous cache population by default. This setting allows the system to prioritize reading data from remote storage (like S3 or HDFS) and returning results to the user immediately, while the task of writing that data to the local disk cache is deferred to a background process.
* Variable Name: enable_datacache_async_populate_mode
* Type: Session variable
* Default: true (since v3.3.0)
* Effect:
* When true (Asynchronous): The first query is faster because it does not wait for the local disk write to complete. However, it may take multiple queries to fully "warm up" the cache since the background worker might not cache everything instantly.
* When false (Synchronous): The system ensures data is written to the local cache before completing the read operation for the query. This ensures high cache efficiency for the very next query but increases the latency of the first query.
Additional Related Settings
1. populate_datacache_mode:
This variable determines which queries are allowed to populate the cache. For example, if you want to avoid "polluting" the cache with one-time full table scans (which could slow down initial queries by triggering massive background writes), you can adjust this mode.
* `0`: Populate for all queries (default).
* `1`: Do not populate for queries that scan the entire table.
2. enable_datacache_io_adapter:
Enabled by default, this feature automatically stops populating the cache if it detects that the local disk I/O load is too high. This prevents cache writing from competing with the query's actual data reading, further protecting initial query performance.
How to check or change the setting:
You can check your current setting or change it for your session:
sql
-- Check current value
SHOW VARIABLES LIKE 'enable_datacache_async_populate_mode';
-- Enable asynchronous population for the current session
SET enable_datacache_async_populate_mode = true;
-- Enable it globally
SET GLOBAL enable_datacache_async_populate_mode = true;
Note: If you are using an older version (prior to v3.3.0), this setting might be false by default, and enabling it can significantly reduce the "cold start" latency of your queries.
References
• data_source/data_cache.md
• data_source/data_cache_troubleshooting.md
• knowledge/usage/best-practice.md
• data_source/block_cache_warmup.md