Query cache stores query results in memory so identical or similar queries are served directly from cache, with no data reads or computation. It is most effective for high-concurrency, repetitive workloads such as stress testing and BI reporting.
Query cache is supported in Hologres V3.1 and later, and is disabled by default.
Prerequisites
Before you begin, make sure you have:
A Hologres instance running V3.1 or later. To upgrade, see Instance upgrades or contact the Hologres support team via DingTalk. For instructions, see How do I get more online support?
Superuser privileges on the target database
How it works
Hologres memory is divided into three categories: query execution, cache, and metadata. The cache layer can use up to 30% of total instance memory. For example, a worker with a 64 GB memory limit can allocate up to 20 GB to cache. Query cache draws from this cache allocation.
When a query arrives, Hologres checks whether a matching result exists in cache. If it does, the result is returned immediately. If not, the query runs normally and the result is stored in cache for subsequent requests.
Consistency model: Query cache uses a weak consistency model. If data is written during the cache retention period, cached results may not reflect the latest writes. For use cases where data freshness is critical, disable query cache or set a shorter TTL.
Queries not cached: Queries containing the RANDOM function are never cached, because their results are non-deterministic.
Enable query cache
Run the following command as a superuser. The change takes effect for new connections only.
-- Enable query cache (requires superuser privileges; takes effect for new connections)
ALTER DATABASE <database_name> SET hg_experimental_enable_query_cache=on;Configure query cache
Set the memory allocation (query_cache_percentage)
Allocate a percentage of the cache layer's memory to query cache. The formula for memory per worker is:
Memory per worker = 20 GB x query_cache_percentage x 0.01
Total memory = Memory per worker x Number of workersFor example, setting query_cache_percentage=2 allocates 400 MB per worker (20 GB x 2 x 0.01).
-- Allocate 2% of cache memory to query cache (400 MB per worker in a 64 GB instance)
SELECT hg_admin_command('set_global_flag', 'query_cache_percentage=2');Set the maximum size per cached result
The default maximum size for a single cached result is 10 MB. The maximum allowed value is 20 GB.
-- Set maximum size per cached result (default: 10 MB, shown here as 10240 KB)
ALTER DATABASE <database_name> SET hg_experimental_query_cache_max_kb_per_item=10240;Set the TTL (time-to-live)
TTL controls how long a cached result remains valid before it expires. The default is 60 seconds.
Choose your TTL based on how often the underlying data changes:
Slowly changing data: set a longer TTL to allow more queries to be served from cache.
Frequently updated data: set a shorter TTL to reduce the risk of stale results, or disable query cache entirely.
Hologres also applies eviction policies based on memory pressure and retention period. For details, see Storage technology deep dive.
-- Set TTL in seconds (default: 60)
ALTER DATABASE <database_name> SET hg_experimental_query_cache_expire_time_sec=60;Parameters
| Parameter | Description | Default | Unit |
|---|---|---|---|
hg_experimental_enable_query_cache | Enables or disables query cache. Requires superuser privileges. Takes effect for new connections only. | off | — |
query_cache_percentage | Percentage of the cache layer's memory allocated to query cache. | — | % |
hg_experimental_query_cache_max_kb_per_item | Maximum memory for a single cached result. Maximum value: 20 GB. | 10240 KB (10 MB) | KB |
hg_experimental_query_cache_expire_time_sec | Cache TTL. Results older than this value are expired and evicted. | 60 | Seconds |
Usage notes
Query cache is disabled by default. Enable it explicitly before use.
Enabling query cache takes effect only for new connections. Existing connections are not affected.
Query cache uses weak consistency. If your workload involves frequent writes and requires up-to-date results, set a shorter TTL or disable query cache.
Queries containing the
RANDOMfunction are not cached.