The cache clause enables the Searcher Cache feature, which caches query results after fine sorting or document dispersal. Subsequent identical queries skip rough sorting and fine sorting entirely, improving query performance at the Searcher worker level.
The cache clause is optional. Add it to a query statement to control caching behavior per request.
The Searcher Cache component caches results after fine sorting. To make sure enough results are cached, set the rank_size parameter in the rerank scorer or the rerank_size parameter in a config clause. If too few results pass fine sorting, the cache may not hold enough documents to satisfy future queries.
Syntax
{
"cache": {
"enabled": true,
"cache_key": 1234567890,
"expire_time": "now()+300",
"current_time": 1235,
"cache_filter": "a > 10",
"cache_doc_num_limit": [200, 3000],
"refresh_attributes": ["price", "sell_count"]
}
}Parameters
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
enabled | Boolean | — | No | Specifies whether to enable the Searcher Cache. Valid values: true, false. |
cache_key | Integer | Hash of the query statement | No | The cache key for the request. A stable cache key improves the cache hit ratio. If omitted, the system computes a hash of the query statement and uses it as the key. |
expire_time | Expression (UINT32) | Never expires | No | The cache duration in seconds. Accepts an attribute expression, function expression, virtual attribute expression, or an arithmetic expression combining these types. The return value must be of UINT32 type; if the returned value is not of the UINT32 type, the system reports an error. Before caching, the system evaluates this expression for each document and uses the minimum value as the cache duration for all cached items. Omit this parameter if your data has no incremental updates or timeliness requirements. |
current_time | Integer | Current system time | No | The reference timestamp for expiry checks. If set, the Searcher Cache component compares expire_time against this value to determine whether a cached item has expired. If omitted, the current system time is used. |
cache_filter | Expression | — | No | Filter conditions applied to cached items. Uses the same syntax as standard filter expressions. |
cache_doc_num_limit | Array of integers | [200, 3000] | No | The maximum number of documents to cache. Specify this parameter in every query statement to maintain a consistent cache hit ratio. Supports tiered limits. |
refresh_attributes | Array of strings | — | No | Attribute fields whose values are refreshed from the index when the cache is hit. Only attribute fields defined in the schema are supported; attribute fields from a virtual_attribute clause are not supported. Use this parameter when the cache duration is long and specific attribute values change frequently. |
How cache_doc_num_limit tiered limits work
The number of documents cached depends on the required_topK value for the query. required_topK is calculated as follows:
Single Searcher worker:
required_topK = start + hitMultiple Searcher workers:
required_topK = min(start + hit, searcher_return_hits), wheresearcher_return_hitsis set by the Query Result Searcher (QRS) worker
With cache_doc_num_limit set to [280, 780], the cache applies the following policies:
required_topK | Documents cached |
|---|---|
| ≤ 280 | 280 |
| 281–780 | 780 |
| > 780 | Equal to required_topK |
Specifying multiple tiers lets the cache serve queries with different topK requirements from the same cached result set, increasing the cache hit ratio.
Example
{
"cache": {
"enabled": true,
"cache_key": 1234567890,
"expire_time": "now()+300",
"current_time": 1235,
"cache_filter": "a > 10",
"cache_doc_num_limit": [200, 3000],
"refresh_attributes": ["price", "sell_count"]
}
}Usage notes
The cache clause is optional. Omit it if caching is not required for a query.
By default, cached items never expire. The Searcher Cache component evicts items using the least recently used (LRU) algorithm when cache capacity is reached.
Set
expire_timeonly when your data has timeliness requirements. For static datasets or datasets without incremental updates, the default (no expiry) is sufficient.To keep cached attribute values current when the cache duration is long, use
refresh_attributesto specify which fields to refresh on each cache hit.Specify
cache_doc_num_limitin every query statement. Inconsistent limits across requests reduce the cache hit ratio.