Clause description
You can use the searcher cache feature to cache final query results after the system performs fine sorting or disperses the documents that are obtained. After you enable the searcher cache feature, the number of rough sorting and fine sorting operations can be reduced and the query performance of each Searcher worker can be improved because the system does not need to repeatedly perform rough sorting and fine sorting on the same data. You can create cache policies as needed. For example, you can specify whether to cache the returned results of a query and specify a cache duration for cached items. You can enable or disable these policies when you configure settings for Searcher workers or write query statements. OpenSearch Vector Search Edition provides plug-ins that you can use to create cache policies as needed.
Syntax
{
"cache" : {
}
}Parameters:
enabled: specifies whether to enable the searcher cache feature. Valid values: true and false.
cache_key: The key for the current request. You must generate this key and specify it in the request. The key generation strategy affects the cache hit rate. To ensure a high hit rate, you must generate a suitable key based on your application's scenario and business needs. If you do not specify a key, the system uses a hash of the entire request as the default cache key.
expire_time: The expiration time for an item in the Searcher Cache. This parameter ensures the timeliness of the results. This setting depends on the specific application. If your application is not concerned with timeliness or does not have incremental updates, you can omit this parameter. By default, items never expire and are removed only by the cache's least recently used (LRU) policy. The `expire_time` can be any expression supported by HA3, such as an attribute expression, a function expression, a virtual attribute expression, or an arithmetic expression that combines the three. The return value must be a `uint32` type. Otherwise, an error is reported. The unit for `expire_time` is seconds (s). Before caching the query results, the Searcher Cache uses the `expire_time` expression to calculate an expiration time for each document in the results. It then uses the minimum of these times as the expiration time for the entire cached result of the request.
current_time: If you specify the current_time parameter in the cache clause, the Searcher Cache component compares the values of the expire_time and current_time parameters to determine whether a cached item expires. If you do not specify the current_time parameter in the cache clause, the Searcher Cache component compares the value of the expire_time parameter with the current system time to determine whether a cached item expires.
cache_filter: the conditions used to filter the cached items. The filtering syntax is the same as the standard filtering syntax.
cache_doc_num_limit: Specifies the number of documents from the query result to cache. To improve the cache hit rate, specify this parameter in each query. The default value is `[200, 3000]`. You can also configure multiple levels, such as `[100, 200, 300]`. For example, if you set `cache_doc_num_limit` to `[280, 780]`, the caching policy is as follows: If `required_topK` in the searcher is less than or equal to 280, 280 documents are cached. If `required_topK` is greater than 280 and less than or equal to 780, 780 documents are cached. If `required_topK` is greater than 780, `required_topK` documents are cached.
refresh_attributes: the attribute fields whose values the system needs to update to the cache when the cache is hit. You can specify only the attribute fields that are included in the schema. Attribute fields that are specified in a virtual_attribute clause are not supported. If the cache duration is long and the values of specific attribute fields are updated, the cached attribute field values may be outdated. You can specify the refresh_attributes parameter to ensure that the system caches the most recent values of attribute fields. This helps ensure high timeliness of cached attribute field values.
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
A cache clause is optional.
The number of documents that the system can cache is based on the value of the required_topK parameter of the Searcher worker. The value of the required_topK parameter varies based on the value that is calculated based on the following formula: start + hit. If your application uses multiple Searcher workers, the Query Result Searcher (QRS) worker limits the number of documents that each Searcher worker can return based on the value of the searcher_return_hits parameter. In this case, the value of the required_topK parameter is calculated based on the following expression: min(start + hit, searcher_return_hits).
The Searcher Cache component caches the results after fine sorting is performed. To ensure that sufficient results are cached, make sure that the system returns a specific number of results after fine sorting is performed. You can specify the rank_size parameter in the rerank scorer or specify the rerank_size parameter in a config clause.