Index request cache

The OpenSearch index request cache is a specialized caching mechanism designed to enhance search performance by storing the results of frequently executed search queries at the shard level. This reduces cluster load and improves response times for repeated searches. This cache is enabled by default and is particularly useful for read-heavy workloads where certain queries are executed frequently.

The cache is automatically invalidated at the configured refresh interval. The invalidation includes document updates (including document deletions) and changes to index settings. This ensures that stale results are never returned from the cache. When the cache size exceeds its configured limit, the least recently used entries are evicted to make room for new entries.

Search requests with size=0 are cached in the request cache by default. Search requests with non-deterministic characteristics (such as Math.random()) or relative times (such as now or new Date()) are ineligible for caching.

Configuring request caching

You can configure the index request cache by setting the parameters in the opensearch.yml configuration file or using the REST API. For more information, see Index settings.

Settings

The following table lists the index request cache settings. For more information about dynamic settings, see Index settings.

SettingData typeDefaultLevelStatic/DynamicDescription
indices.cache.cleanup_intervalTime unit1m (1 minute)ClusterStaticSchedules a recurring background task that cleans up expired entries from the cache at the specified interval.
indices.requests.cache.sizePercentage1%ClusterStaticThe cache size as a percentage of the heap size (for example, to use 1% of the heap, specify 1%).
index.requests.cache.enableBooleantrueIndexDynamicEnables or disables the request cache.

Example

To disable the request cache for an index, send the following request:

  1. PUT /my_index/_settings
  2. {
  3.   "index.requests.cache.enable": false
  4. }

copy

Caching specific requests

In addition to providing index-level or cluster-level settings for the request cache, you can also cache specific search requests selectively by setting the request_cache query parameter to true:

  1. GET /students/_search?request_cache=true
  2. {
  3.   "query": {
  4.     "match": {
  5.       "name": "doe john"
  6.     }
  7.   }
  8. }

copy

Monitoring the request cache

Monitoring cache usage and performance is crucial to maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache.

Retrieving cache statistics for all nodes

The Nodes Stats API returns cache statistics for all nodes in a cluster:

  1. GET /_nodes/stats/indices/request_cache

copy

The response contains the request cache statistics:

  1. {
  2.   "nodes": {
  3.     "T7aqO6zaQX-lt8XBWBYLsA": {
  4.       "indices": {
  5.         "request_cache": {
  6.           "memory_size_in_bytes": 10240,
  7.           "evictions": 0,
  8.           "hit_count": 50,
  9.           "miss_count": 10
  10.         }
  11.       }
  12.     }
  13.   }
  14. }

copy

Retrieving cache statistics for a specific index

The Index Stats API returns cache statistics for a specific index:

  1. GET /my_index/_stats/request_cache

copy

The response contains the request cache statistics:

  1. {
  2.   "_shards": {
  3.     "total": 5,
  4.     "successful": 5,
  5.     "failed": 0
  6.   },
  7.   "_all": {
  8.     "primaries": {
  9.       "request_cache": {
  10.         "memory_size_in_bytes": 2048,
  11.         "evictions": 1,
  12.         "hit_count": 30,
  13.         "miss_count": 5
  14.       }
  15.     },
  16.     "total": {
  17.       "request_cache": {
  18.         "memory_size_in_bytes": 4096,
  19.         "evictions": 2,
  20.         "hit_count": 60,
  21.         "miss_count": 10
  22.       }
  23.     }
  24.   },
  25.   "indices": {
  26.     "my_index": {
  27.       "primaries": {
  28.         "request_cache": {
  29.           "memory_size_in_bytes": 2048,
  30.           "evictions": 1,
  31.           "hit_count": 30,
  32.           "miss_count": 5
  33.         }
  34.       },
  35.       "total":{
  36.         "request_cache": {
  37.           "memory_size_in_bytes": 4096,
  38.           "evictions": 2,
  39.           "hit_count": 60,
  40.           "miss_count": 10
  41.         }
  42.       }
  43.     }
  44.   }
  45. }

Best practices

When using the index request cache, consider the following best practices:

  • Appropriate cache size: Configure the cache size based on your query patterns. A larger cache can store more results but may consume significant resources.
  • Query optimization: Ensure that frequently executed queries are optimized so that they can benefit from caching.
  • Monitoring: Regularly monitor cache hit and cache miss rates to understand cache efficiency and make necessary adjustments.