From 17b0b94a733d09d82f9e8a92a1e344a60305f9a9 Mon Sep 17 00:00:00 2001 From: Kiran Prakash Date: Mon, 3 Jun 2024 16:27:53 -0700 Subject: [PATCH 01/10] Create doc for Indices Request Cache Signed-off-by: Kiran Prakash --- search/caching/request-cache/index.md | 144 ++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 search/caching/request-cache/index.md diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md new file mode 100644 index 0000000000..13e31e9948 --- /dev/null +++ b/search/caching/request-cache/index.md @@ -0,0 +1,144 @@ +--- +layout: default +title: Indices Request Cache +parent: Improving search performance +has_children: true +nav_order: 100 +--- + +# Indices Request Cache + +The Indices Request Cache in OpenSearch 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 the load on the cluster 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. + +It is important to note the cache is automatically invalidated on refresh intervals with corresponding document updates (including document deletions) and changes to index settings, thereby ensuring 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 Eligible for Indices Request Cache +Search requests with `size=0` are by default cached in request cache. Search requests with non-deterministic characteristics such as `Math.random()`, relative times like `now`, `new Date()` are **ineligible** for caching. + +You can also cache search requests selectively by setting the `request_cache` parameter to `true` in the request parameters. For example: +```json +GET /students/_search?request_cache=true +{ + "query": { + "match": { + "name": "doe john" + } + } +} +``` + +## Configuration +Configuring the Indices Request Cache involves setting parameters in the opensearch.yml configuration file or using the OpenSearch REST API. + +### Configuration Parameters: + +The following table lists the settings for configuring the Indices Request Cache, configure the following settings in `opensearch.yml`: + +Setting | Data type | Default | Description +:--- |:-----------|:--------| :--- +`indices.requests.cache.size` | Percentage | 1% | The size of the cache. Optional. +`index.requests.cache.enable` | Boolean | true | Enables or disables the request cache. Optional. +`indices.cache.cleanup_interval` | Time unit | 1 min | Schedule of the Recurring background task that cleans up expired entries from the cache. Optional. + +#### Using REST API + +To disable the request cache for an index: +```json +PUT /my_index/_settings +{ + "index.requests.cache.enable": false +} +``` +{% include copy-curl.html %} + +To update the cache size dynamically: +```json +PUT /_cluster/settings +{ + "persistent": { + "indices.requests.cache.size": "1%" + } +} +``` +{% include copy-curl.html %} + +### Monitoring and Management +Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. + +#### Retrieving Cache Statistics for All Nodes: +`GET /_nodes/stats/indices/request_cache` returns cache statistics for all nodes in the cluster. + +```json +{ + "nodes": { + "T7aqO6zaQX-lt8XBWBYLsA": { + "indices": { + "request_cache": { + "memory_size_in_bytes": 10240, + "evictions": 0, + "hit_count": 50, + "miss_count": 10 + } + } + } + } +} +``` +{% include copy-curl.html %} + +#### Retrieving Cache Statistics for a Specific Index: + +`GET /my_index/_stats/request_cache` returns cache statistics for a specific index. +```json +{ + "_shards": { + "total": 5, + "successful": 5, + "failed": 0 + }, + "_all": { + "primaries": { + "request_cache": { + "memory_size_in_bytes": 2048, + "evictions": 1, + "hit_count": 30, + "miss_count": 5 + } + }, + "total": { + "request_cache": { + "memory_size_in_bytes": 4096, + "evictions": 2, + "hit_count": 60, + "miss_count": 10 + } + } + }, + "indices": { + "my_index": { + "primaries": { + "request_cache": { + "memory_size_in_bytes": 2048, + "evictions": 1, + "hit_count": 30, + "miss_count": 5 + } + }, + "total":{ + "request_cache": { + "memory_size_in_bytes": 4096, + "evictions": 2, + "hit_count": 60, + "miss_count": 10 + } + } + } + } +} +``` + +### Best Practices + +- **Appropriate Cache Size**: Configure the cache size based on query patterns. A larger cache can store more results but may consume significant resources. +- **Query Optimization**: Ensure that frequently executed queries are optimized to benefit from caching. +- **Monitoring**: Regularly monitor cache hits and cache miss rates to understand cache efficiency and make necessary adjustments. \ No newline at end of file From bdb2d8c22d06b10961fb47194a0cd6ef3d739852 Mon Sep 17 00:00:00 2001 From: Kiran Prakash Date: Mon, 3 Jun 2024 16:41:28 -0700 Subject: [PATCH 02/10] sentence case Signed-off-by: Kiran Prakash --- search/caching/request-cache/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md index 13e31e9948..d071080426 100644 --- a/search/caching/request-cache/index.md +++ b/search/caching/request-cache/index.md @@ -6,13 +6,13 @@ has_children: true nav_order: 100 --- -# Indices Request Cache +# Indices request cache The Indices Request Cache in OpenSearch 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 the load on the cluster 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. It is important to note the cache is automatically invalidated on refresh intervals with corresponding document updates (including document deletions) and changes to index settings, thereby ensuring 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 Eligible for Indices Request Cache +## Search requests eligible for indices request cache Search requests with `size=0` are by default cached in request cache. Search requests with non-deterministic characteristics such as `Math.random()`, relative times like `now`, `new Date()` are **ineligible** for caching. You can also cache search requests selectively by setting the `request_cache` parameter to `true` in the request parameters. For example: @@ -30,7 +30,7 @@ GET /students/_search?request_cache=true ## Configuration Configuring the Indices Request Cache involves setting parameters in the opensearch.yml configuration file or using the OpenSearch REST API. -### Configuration Parameters: +### Configuration parameters: The following table lists the settings for configuring the Indices Request Cache, configure the following settings in `opensearch.yml`: @@ -62,7 +62,7 @@ PUT /_cluster/settings ``` {% include copy-curl.html %} -### Monitoring and Management +### Monitoring and management Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. #### Retrieving Cache Statistics for All Nodes: From 248a0cedcca3f1586d5bd71fff9661979e4310bb Mon Sep 17 00:00:00 2001 From: Kiran Prakash Date: Mon, 3 Jun 2024 16:50:11 -0700 Subject: [PATCH 03/10] sentence case Signed-off-by: Kiran Prakash --- search/caching/request-cache/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md index d071080426..8b826632fc 100644 --- a/search/caching/request-cache/index.md +++ b/search/caching/request-cache/index.md @@ -65,7 +65,7 @@ PUT /_cluster/settings ### Monitoring and management Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. -#### Retrieving Cache Statistics for All Nodes: +#### Retrieving cache statistics for all nodes: `GET /_nodes/stats/indices/request_cache` returns cache statistics for all nodes in the cluster. ```json @@ -86,7 +86,7 @@ Monitoring the cache usage and performance is crucial for maintaining an efficie ``` {% include copy-curl.html %} -#### Retrieving Cache Statistics for a Specific Index: +#### Retrieving cache statistics for a specific index: `GET /my_index/_stats/request_cache` returns cache statistics for a specific index. ```json @@ -137,7 +137,7 @@ Monitoring the cache usage and performance is crucial for maintaining an efficie } ``` -### Best Practices +### Best practices - **Appropriate Cache Size**: Configure the cache size based on query patterns. A larger cache can store more results but may consume significant resources. - **Query Optimization**: Ensure that frequently executed queries are optimized to benefit from caching. From dc6e12ffb6bba7c840c48649ed65bb5d2e660fe1 Mon Sep 17 00:00:00 2001 From: Kiran Prakash Date: Mon, 3 Jun 2024 16:27:53 -0700 Subject: [PATCH 04/10] Create doc for Indices Request Cache Signed-off-by: Kiran Prakash --- search/caching/request-cache/index.md | 144 ++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 search/caching/request-cache/index.md diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md new file mode 100644 index 0000000000..13e31e9948 --- /dev/null +++ b/search/caching/request-cache/index.md @@ -0,0 +1,144 @@ +--- +layout: default +title: Indices Request Cache +parent: Improving search performance +has_children: true +nav_order: 100 +--- + +# Indices Request Cache + +The Indices Request Cache in OpenSearch 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 the load on the cluster 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. + +It is important to note the cache is automatically invalidated on refresh intervals with corresponding document updates (including document deletions) and changes to index settings, thereby ensuring 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 Eligible for Indices Request Cache +Search requests with `size=0` are by default cached in request cache. Search requests with non-deterministic characteristics such as `Math.random()`, relative times like `now`, `new Date()` are **ineligible** for caching. + +You can also cache search requests selectively by setting the `request_cache` parameter to `true` in the request parameters. For example: +```json +GET /students/_search?request_cache=true +{ + "query": { + "match": { + "name": "doe john" + } + } +} +``` + +## Configuration +Configuring the Indices Request Cache involves setting parameters in the opensearch.yml configuration file or using the OpenSearch REST API. + +### Configuration Parameters: + +The following table lists the settings for configuring the Indices Request Cache, configure the following settings in `opensearch.yml`: + +Setting | Data type | Default | Description +:--- |:-----------|:--------| :--- +`indices.requests.cache.size` | Percentage | 1% | The size of the cache. Optional. +`index.requests.cache.enable` | Boolean | true | Enables or disables the request cache. Optional. +`indices.cache.cleanup_interval` | Time unit | 1 min | Schedule of the Recurring background task that cleans up expired entries from the cache. Optional. + +#### Using REST API + +To disable the request cache for an index: +```json +PUT /my_index/_settings +{ + "index.requests.cache.enable": false +} +``` +{% include copy-curl.html %} + +To update the cache size dynamically: +```json +PUT /_cluster/settings +{ + "persistent": { + "indices.requests.cache.size": "1%" + } +} +``` +{% include copy-curl.html %} + +### Monitoring and Management +Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. + +#### Retrieving Cache Statistics for All Nodes: +`GET /_nodes/stats/indices/request_cache` returns cache statistics for all nodes in the cluster. + +```json +{ + "nodes": { + "T7aqO6zaQX-lt8XBWBYLsA": { + "indices": { + "request_cache": { + "memory_size_in_bytes": 10240, + "evictions": 0, + "hit_count": 50, + "miss_count": 10 + } + } + } + } +} +``` +{% include copy-curl.html %} + +#### Retrieving Cache Statistics for a Specific Index: + +`GET /my_index/_stats/request_cache` returns cache statistics for a specific index. +```json +{ + "_shards": { + "total": 5, + "successful": 5, + "failed": 0 + }, + "_all": { + "primaries": { + "request_cache": { + "memory_size_in_bytes": 2048, + "evictions": 1, + "hit_count": 30, + "miss_count": 5 + } + }, + "total": { + "request_cache": { + "memory_size_in_bytes": 4096, + "evictions": 2, + "hit_count": 60, + "miss_count": 10 + } + } + }, + "indices": { + "my_index": { + "primaries": { + "request_cache": { + "memory_size_in_bytes": 2048, + "evictions": 1, + "hit_count": 30, + "miss_count": 5 + } + }, + "total":{ + "request_cache": { + "memory_size_in_bytes": 4096, + "evictions": 2, + "hit_count": 60, + "miss_count": 10 + } + } + } + } +} +``` + +### Best Practices + +- **Appropriate Cache Size**: Configure the cache size based on query patterns. A larger cache can store more results but may consume significant resources. +- **Query Optimization**: Ensure that frequently executed queries are optimized to benefit from caching. +- **Monitoring**: Regularly monitor cache hits and cache miss rates to understand cache efficiency and make necessary adjustments. \ No newline at end of file From e875badcf8f424f841e4c67fc7db35e51c5a165a Mon Sep 17 00:00:00 2001 From: Kiran Prakash Date: Mon, 3 Jun 2024 16:41:28 -0700 Subject: [PATCH 05/10] sentence case Signed-off-by: Kiran Prakash --- search/caching/request-cache/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md index 13e31e9948..d071080426 100644 --- a/search/caching/request-cache/index.md +++ b/search/caching/request-cache/index.md @@ -6,13 +6,13 @@ has_children: true nav_order: 100 --- -# Indices Request Cache +# Indices request cache The Indices Request Cache in OpenSearch 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 the load on the cluster 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. It is important to note the cache is automatically invalidated on refresh intervals with corresponding document updates (including document deletions) and changes to index settings, thereby ensuring 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 Eligible for Indices Request Cache +## Search requests eligible for indices request cache Search requests with `size=0` are by default cached in request cache. Search requests with non-deterministic characteristics such as `Math.random()`, relative times like `now`, `new Date()` are **ineligible** for caching. You can also cache search requests selectively by setting the `request_cache` parameter to `true` in the request parameters. For example: @@ -30,7 +30,7 @@ GET /students/_search?request_cache=true ## Configuration Configuring the Indices Request Cache involves setting parameters in the opensearch.yml configuration file or using the OpenSearch REST API. -### Configuration Parameters: +### Configuration parameters: The following table lists the settings for configuring the Indices Request Cache, configure the following settings in `opensearch.yml`: @@ -62,7 +62,7 @@ PUT /_cluster/settings ``` {% include copy-curl.html %} -### Monitoring and Management +### Monitoring and management Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. #### Retrieving Cache Statistics for All Nodes: From 7e2a43a2cdfb7d9efca5b31c2c04d77266b669ac Mon Sep 17 00:00:00 2001 From: Kiran Prakash Date: Mon, 3 Jun 2024 16:50:11 -0700 Subject: [PATCH 06/10] sentence case Signed-off-by: Kiran Prakash --- search/caching/request-cache/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md index d071080426..8b826632fc 100644 --- a/search/caching/request-cache/index.md +++ b/search/caching/request-cache/index.md @@ -65,7 +65,7 @@ PUT /_cluster/settings ### Monitoring and management Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. -#### Retrieving Cache Statistics for All Nodes: +#### Retrieving cache statistics for all nodes: `GET /_nodes/stats/indices/request_cache` returns cache statistics for all nodes in the cluster. ```json @@ -86,7 +86,7 @@ Monitoring the cache usage and performance is crucial for maintaining an efficie ``` {% include copy-curl.html %} -#### Retrieving Cache Statistics for a Specific Index: +#### Retrieving cache statistics for a specific index: `GET /my_index/_stats/request_cache` returns cache statistics for a specific index. ```json @@ -137,7 +137,7 @@ Monitoring the cache usage and performance is crucial for maintaining an efficie } ``` -### Best Practices +### Best practices - **Appropriate Cache Size**: Configure the cache size based on query patterns. A larger cache can store more results but may consume significant resources. - **Query Optimization**: Ensure that frequently executed queries are optimized to benefit from caching. From 783cc7a40a05f816fed0264dab58cef0f12d0d5f Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 13 Jun 2024 15:14:31 -0400 Subject: [PATCH 07/10] Doc review Signed-off-by: Fanit Kolchina --- .../configuring-opensearch/index-settings.md | 6 + _search-plugins/caching/index.md | 2 +- _search-plugins/caching/request-cache.md | 171 ++++++++++++++++++ search/caching/request-cache/index.md | 144 --------------- 4 files changed, 178 insertions(+), 145 deletions(-) create mode 100644 _search-plugins/caching/request-cache.md delete mode 100644 search/caching/request-cache/index.md diff --git a/_install-and-configure/configuring-opensearch/index-settings.md b/_install-and-configure/configuring-opensearch/index-settings.md index 543fa92b0d..191ffc616b 100644 --- a/_install-and-configure/configuring-opensearch/index-settings.md +++ b/_install-and-configure/configuring-opensearch/index-settings.md @@ -37,6 +37,10 @@ OpenSearch supports the following cluster-level index settings. All settings in - `indices.replication.max_bytes_per_sec` (String): Limits the total inbound and outbound replication traffic for each node. If a value is not specified in the configured value the `indices.recovery.max_bytes_per_sec` setting is used, which defaults to 40 mb. If you set the replication traffic value to less than or equal to 0 mb, rate limiting is disabled, which causes replication data to be transferred at the highest possible rate. +- `indices.requests.cache.size` (String): The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). Default is `1%`. For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). + +- `indices.cache.cleanup_interval` (Time unit): Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. Default is `1m` (1 minute). For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). + - `indices.fielddata.cache.size` (String): The maximum size of the field data cache. May be specified as an absolute value (for example, `8GB`) or a percentage of the node heap (for example, `50%`). This value is static so you must specify it in the `opensearch.yml` file. If you don't specify this setting, the maximum size is unlimited. This value should be smaller than the `indices.breaker.fielddata.limit`. For more information, see [Field data circuit breaker]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/circuit-breaker/#field-data-circuit-breaker-settings). - `cluster.remote_store.index.path.type` (String): The path strategy for the data stored in the remote store. This setting is effective only for remote-store-enabled clusters. This setting supports the following values: @@ -203,6 +207,8 @@ OpenSearch supports the following dynamic index-level index settings: - `index.query.max_nested_depth` (Integer): The maximum number of nesting levels for `nested` queries. Default is `Integer.MAX_VALUE`. Minimum is 1 (single `nested` query). +- `index.requests.cache.enable` (Boolean): Enables or disables the index request cache. Default is `true`. For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). + - `index.routing.allocation.enable` (String): Specifies options for the index’s shard allocation. Available options are `all` (allow allocation for all shards), `primaries` (allow allocation only for primary shards), `new_primaries` (allow allocation only for new primary shards), and `none` (do not allow allocation). Default is `all`. - `index.routing.rebalance.enable` (String): Enables shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). Default is `all`. diff --git a/_search-plugins/caching/index.md b/_search-plugins/caching/index.md index d155caf86b..000d0b61c1 100644 --- a/_search-plugins/caching/index.md +++ b/_search-plugins/caching/index.md @@ -16,7 +16,7 @@ Understanding how your data uses the cache can help improve your cluster's perfo OpenSearch supports the following on-heap cache types: -- **Request cache**: Caches the local results on each shard. This allows frequently used and potentially resource-heavy search requests to return results almost instantaneously. +- [**Index request cache**]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/): Caches the local results on each shard. This allows frequently used and potentially resource-heavy search requests to return results almost instantaneously. - **Query cache**: Caches common data from similar queries at the shard level. The query cache is more granular than the request cache and can cache data to be reused in different queries. - **Field data cache**: Caches field data and global ordinals, which are both used to support aggregations on certain field types. diff --git a/_search-plugins/caching/request-cache.md b/_search-plugins/caching/request-cache.md new file mode 100644 index 0000000000..6e9af18572 --- /dev/null +++ b/_search-plugins/caching/request-cache.md @@ -0,0 +1,171 @@ +--- +layout: default +title: Index request cache +parent: Caching +grand_parent: Improving search performance +nav_order: 5 +--- + +# Index request cache + +The index request cache in OpenSearch 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 the load on the cluster 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. +{: .note} + +## Configuring request caching + +You can configure index request cache by setting the parameters in the `opensearch.yml` configuration file or using the REST API. For more information, see [Index settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index-settings/). + +### Settings + +The following table lists the index request cache settings. All settings are dynamic. For more information about dynamic settings, see [Dynamic settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/#dynamic-settings). + +Setting | Data type | Default | Level | Description +:--- |:-----------|:--------| :--- | :--- +`indices.cache.cleanup_interval` | Time unit | `1m` (1 minute) | Cluster | Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. +`indices.requests.cache.size` | Percentage | `1%` | Cluster | The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). +`index.requests.cache.enable` | Boolean | `true` | Index | Enables or disables the request cache. + + +### REST API examples + +To disable the request cache for an index, send the following request: + +```json +PUT /my_index/_settings +{ + "index.requests.cache.enable": false +} +``` +{% include copy-curl.html %} + +To update the cache size dynamically for the whole cluster, send the following request: + +```json +PUT /_cluster/settings +{ + "persistent": { + "indices.requests.cache.size": "1%" + } +} +``` +{% include copy-curl.html %} + +## Caching specific requests + +In addition to providing index-level or cluster-level settings for request cache, you can also cache specific search requests selectively by setting the `request_cache` query parameter to `true`: + +```json +GET /students/_search?request_cache=true +{ + "query": { + "match": { + "name": "doe john" + } + } +} +``` +{% include copy-curl.html %} + +## Monitoring the request cache + +Monitoring cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. + +### Retrieving cache statistics for all nodes + +The [Nodes Stats API]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/nodes-stats/) returns cache statistics for all nodes in the cluster: + +```json +GET /_nodes/stats/indices/request_cache +``` +{% include copy-curl.html %} + +The response contains the request cache statistics: + +```json +{ + "nodes": { + "T7aqO6zaQX-lt8XBWBYLsA": { + "indices": { + "request_cache": { + "memory_size_in_bytes": 10240, + "evictions": 0, + "hit_count": 50, + "miss_count": 10 + } + } + } + } +} +``` +{% include copy-curl.html %} + +### Retrieving cache statistics for a specific index + +The [Index Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/stats/) returns cache statistics for a specific index: + +```json +GET /my_index/_stats/request_cache +``` +{% include copy-curl.html %} + +The response contains the request cache statistics: + +```json +{ + "_shards": { + "total": 5, + "successful": 5, + "failed": 0 + }, + "_all": { + "primaries": { + "request_cache": { + "memory_size_in_bytes": 2048, + "evictions": 1, + "hit_count": 30, + "miss_count": 5 + } + }, + "total": { + "request_cache": { + "memory_size_in_bytes": 4096, + "evictions": 2, + "hit_count": 60, + "miss_count": 10 + } + } + }, + "indices": { + "my_index": { + "primaries": { + "request_cache": { + "memory_size_in_bytes": 2048, + "evictions": 1, + "hit_count": 30, + "miss_count": 5 + } + }, + "total":{ + "request_cache": { + "memory_size_in_bytes": 4096, + "evictions": 2, + "hit_count": 60, + "miss_count": 10 + } + } + } + } +} +``` + +## Best practices + +When using 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 they can benefit from caching. +- **Monitoring**: Regularly monitor cache hit and cache miss rates to understand cache efficiency and make necessary adjustments. \ No newline at end of file diff --git a/search/caching/request-cache/index.md b/search/caching/request-cache/index.md deleted file mode 100644 index 8b826632fc..0000000000 --- a/search/caching/request-cache/index.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -layout: default -title: Indices Request Cache -parent: Improving search performance -has_children: true -nav_order: 100 ---- - -# Indices request cache - -The Indices Request Cache in OpenSearch 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 the load on the cluster 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. - -It is important to note the cache is automatically invalidated on refresh intervals with corresponding document updates (including document deletions) and changes to index settings, thereby ensuring 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 eligible for indices request cache -Search requests with `size=0` are by default cached in request cache. Search requests with non-deterministic characteristics such as `Math.random()`, relative times like `now`, `new Date()` are **ineligible** for caching. - -You can also cache search requests selectively by setting the `request_cache` parameter to `true` in the request parameters. For example: -```json -GET /students/_search?request_cache=true -{ - "query": { - "match": { - "name": "doe john" - } - } -} -``` - -## Configuration -Configuring the Indices Request Cache involves setting parameters in the opensearch.yml configuration file or using the OpenSearch REST API. - -### Configuration parameters: - -The following table lists the settings for configuring the Indices Request Cache, configure the following settings in `opensearch.yml`: - -Setting | Data type | Default | Description -:--- |:-----------|:--------| :--- -`indices.requests.cache.size` | Percentage | 1% | The size of the cache. Optional. -`index.requests.cache.enable` | Boolean | true | Enables or disables the request cache. Optional. -`indices.cache.cleanup_interval` | Time unit | 1 min | Schedule of the Recurring background task that cleans up expired entries from the cache. Optional. - -#### Using REST API - -To disable the request cache for an index: -```json -PUT /my_index/_settings -{ - "index.requests.cache.enable": false -} -``` -{% include copy-curl.html %} - -To update the cache size dynamically: -```json -PUT /_cluster/settings -{ - "persistent": { - "indices.requests.cache.size": "1%" - } -} -``` -{% include copy-curl.html %} - -### Monitoring and management -Monitoring the cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the cache. - -#### Retrieving cache statistics for all nodes: -`GET /_nodes/stats/indices/request_cache` returns cache statistics for all nodes in the cluster. - -```json -{ - "nodes": { - "T7aqO6zaQX-lt8XBWBYLsA": { - "indices": { - "request_cache": { - "memory_size_in_bytes": 10240, - "evictions": 0, - "hit_count": 50, - "miss_count": 10 - } - } - } - } -} -``` -{% include copy-curl.html %} - -#### Retrieving cache statistics for a specific index: - -`GET /my_index/_stats/request_cache` returns cache statistics for a specific index. -```json -{ - "_shards": { - "total": 5, - "successful": 5, - "failed": 0 - }, - "_all": { - "primaries": { - "request_cache": { - "memory_size_in_bytes": 2048, - "evictions": 1, - "hit_count": 30, - "miss_count": 5 - } - }, - "total": { - "request_cache": { - "memory_size_in_bytes": 4096, - "evictions": 2, - "hit_count": 60, - "miss_count": 10 - } - } - }, - "indices": { - "my_index": { - "primaries": { - "request_cache": { - "memory_size_in_bytes": 2048, - "evictions": 1, - "hit_count": 30, - "miss_count": 5 - } - }, - "total":{ - "request_cache": { - "memory_size_in_bytes": 4096, - "evictions": 2, - "hit_count": 60, - "miss_count": 10 - } - } - } - } -} -``` - -### Best practices - -- **Appropriate Cache Size**: Configure the cache size based on query patterns. A larger cache can store more results but may consume significant resources. -- **Query Optimization**: Ensure that frequently executed queries are optimized to benefit from caching. -- **Monitoring**: Regularly monitor cache hits and cache miss rates to understand cache efficiency and make necessary adjustments. \ No newline at end of file From 4e58b1787e718c27873d315a2cabcb886eac81d7 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 14 Jun 2024 12:31:41 -0400 Subject: [PATCH 08/10] Corrects dynamic/static settings Signed-off-by: Fanit Kolchina --- .../configuring-opensearch/index-settings.md | 20 +++++++++++++------ _search-plugins/caching/request-cache.md | 16 +++++++-------- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/_install-and-configure/configuring-opensearch/index-settings.md b/_install-and-configure/configuring-opensearch/index-settings.md index 191ffc616b..468062a750 100644 --- a/_install-and-configure/configuring-opensearch/index-settings.md +++ b/_install-and-configure/configuring-opensearch/index-settings.md @@ -15,7 +15,20 @@ To learn more about static and dynamic settings, see [Configuring OpenSearch]({{ ## Cluster-level index settings -OpenSearch supports the following cluster-level index settings. All settings in this list are dynamic: +There are two types of cluster settings: + +- [Static cluster-level index settings](#static-cluster-level-index-settings) are settings that you cannot update while the cluster is up. To update a static setting, you must stop the cluster, update the setting, and then restart the cluster. +- [Dynamic cluster-level index settings](#dynamic-cluster-level-index-settings) are settings that you can update at any time. + +### Static cluster-level index settings + +OpenSearch supports the following static cluster-level index settings: + +- `indices.requests.cache.size` (String): The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). Default is `1%`. For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). + +### Dynamic cluster-level index settings + +OpenSearch supports the following dynamic cluster-level index settings: - `action.auto_create_index` (Boolean): Automatically creates an index if the index doesn't already exist. Also applies any index templates that are configured. Default is `true`. @@ -37,8 +50,6 @@ OpenSearch supports the following cluster-level index settings. All settings in - `indices.replication.max_bytes_per_sec` (String): Limits the total inbound and outbound replication traffic for each node. If a value is not specified in the configured value the `indices.recovery.max_bytes_per_sec` setting is used, which defaults to 40 mb. If you set the replication traffic value to less than or equal to 0 mb, rate limiting is disabled, which causes replication data to be transferred at the highest possible rate. -- `indices.requests.cache.size` (String): The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). Default is `1%`. For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). - - `indices.cache.cleanup_interval` (Time unit): Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. Default is `1m` (1 minute). For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). - `indices.fielddata.cache.size` (String): The maximum size of the field data cache. May be specified as an absolute value (for example, `8GB`) or a percentage of the node heap (for example, `50%`). This value is static so you must specify it in the `opensearch.yml` file. If you don't specify this setting, the maximum size is unlimited. This value should be smaller than the `indices.breaker.fielddata.limit`. For more information, see [Field data circuit breaker]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/circuit-breaker/#field-data-circuit-breaker-settings). @@ -109,9 +120,6 @@ For `zstd`, `zstd_no_dict`, `qat_lz4`, and `qat_deflate`, you can specify the co - `index.codec.qatmode` (String): The hardware acceleration mode used for the `qat_lz4` and `qat_deflate` compression codecs. Valid values are `auto` and `hardware`. For more information, see [Index codec settings]({{site.url}}{{site.baseurl}}/im-plugin/index-codecs/). Optional. Default is `auto`. - - - - `index.routing_partition_size` (Integer): The number of shards a custom routing value can go to. Routing helps an imbalanced cluster by relocating values to a subset of shards rather than a single shard. To enable routing, set this value to greater than 1 but less than `index.number_of_shards`. Default is 1. - `index.soft_deletes.retention_lease.period` (Time unit): The maximum amount of time to retain a shard's history of operations. Default is `12h`. diff --git a/_search-plugins/caching/request-cache.md b/_search-plugins/caching/request-cache.md index 6e9af18572..c046c80587 100644 --- a/_search-plugins/caching/request-cache.md +++ b/_search-plugins/caching/request-cache.md @@ -21,13 +21,13 @@ You can configure index request cache by setting the parameters in the `opensear ### Settings -The following table lists the index request cache settings. All settings are dynamic. For more information about dynamic settings, see [Dynamic settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/#dynamic-settings). +The following table lists the index request cache settings. For more information about dynamic settings, see [Index settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index-settings/). -Setting | Data type | Default | Level | Description -:--- |:-----------|:--------| :--- | :--- -`indices.cache.cleanup_interval` | Time unit | `1m` (1 minute) | Cluster | Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. -`indices.requests.cache.size` | Percentage | `1%` | Cluster | The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). -`index.requests.cache.enable` | Boolean | `true` | Index | Enables or disables the request cache. +Setting | Data type | Default | Level | Static/Dynamic | Description +:--- |:-----------|:--------| :--- | :--- | :--- +`indices.cache.cleanup_interval` | Time unit | `1m` (1 minute) | Cluster | Dynamic | Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. +`indices.requests.cache.size` | Percentage | `1%` | Cluster | Static | The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). +`index.requests.cache.enable` | Boolean | `true` | Index | Dynamic | Enables or disables the request cache. ### REST API examples @@ -42,13 +42,13 @@ PUT /my_index/_settings ``` {% include copy-curl.html %} -To update the cache size dynamically for the whole cluster, send the following request: +To update the cache cleanup interval dynamically for the whole cluster, send the following request: ```json PUT /_cluster/settings { "persistent": { - "indices.requests.cache.size": "1%" + "indices.cache.cleanup_interval": "1m" } } ``` From 36d5d298c57cce831638a0907e7a8395a34647b5 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 14 Jun 2024 14:38:37 -0400 Subject: [PATCH 09/10] Move one of the settings to static Signed-off-by: Fanit Kolchina --- .../configuring-opensearch/index-settings.md | 4 ++-- _search-plugins/caching/request-cache.md | 17 ++--------------- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/_install-and-configure/configuring-opensearch/index-settings.md b/_install-and-configure/configuring-opensearch/index-settings.md index 468062a750..2e313cc1f4 100644 --- a/_install-and-configure/configuring-opensearch/index-settings.md +++ b/_install-and-configure/configuring-opensearch/index-settings.md @@ -24,6 +24,8 @@ There are two types of cluster settings: OpenSearch supports the following static cluster-level index settings: +- `indices.cache.cleanup_interval` (Time unit): Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. Default is `1m` (1 minute). For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). + - `indices.requests.cache.size` (String): The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). Default is `1%`. For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). ### Dynamic cluster-level index settings @@ -50,8 +52,6 @@ OpenSearch supports the following dynamic cluster-level index settings: - `indices.replication.max_bytes_per_sec` (String): Limits the total inbound and outbound replication traffic for each node. If a value is not specified in the configured value the `indices.recovery.max_bytes_per_sec` setting is used, which defaults to 40 mb. If you set the replication traffic value to less than or equal to 0 mb, rate limiting is disabled, which causes replication data to be transferred at the highest possible rate. -- `indices.cache.cleanup_interval` (Time unit): Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. Default is `1m` (1 minute). For more information, see [Index request cache]({{site.url}}{{site.baseurl}}/search-plugins/caching/request-cache/). - - `indices.fielddata.cache.size` (String): The maximum size of the field data cache. May be specified as an absolute value (for example, `8GB`) or a percentage of the node heap (for example, `50%`). This value is static so you must specify it in the `opensearch.yml` file. If you don't specify this setting, the maximum size is unlimited. This value should be smaller than the `indices.breaker.fielddata.limit`. For more information, see [Field data circuit breaker]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/circuit-breaker/#field-data-circuit-breaker-settings). - `cluster.remote_store.index.path.type` (String): The path strategy for the data stored in the remote store. This setting is effective only for remote-store-enabled clusters. This setting supports the following values: diff --git a/_search-plugins/caching/request-cache.md b/_search-plugins/caching/request-cache.md index c046c80587..9a4f40d8ea 100644 --- a/_search-plugins/caching/request-cache.md +++ b/_search-plugins/caching/request-cache.md @@ -25,12 +25,11 @@ The following table lists the index request cache settings. For more information Setting | Data type | Default | Level | Static/Dynamic | Description :--- |:-----------|:--------| :--- | :--- | :--- -`indices.cache.cleanup_interval` | Time unit | `1m` (1 minute) | Cluster | Dynamic | Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. +`indices.cache.cleanup_interval` | Time unit | `1m` (1 minute) | Cluster | Static | Schedules a recurring background task that cleans up expired entries from the cache at the specified interval. `indices.requests.cache.size` | Percentage | `1%` | Cluster | Static | The cache size as a percentage of the heap size (for example, to use 1% of the heap, specify `1%`). `index.requests.cache.enable` | Boolean | `true` | Index | Dynamic | Enables or disables the request cache. - -### REST API examples +### Example To disable the request cache for an index, send the following request: @@ -42,18 +41,6 @@ PUT /my_index/_settings ``` {% include copy-curl.html %} -To update the cache cleanup interval dynamically for the whole cluster, send the following request: - -```json -PUT /_cluster/settings -{ - "persistent": { - "indices.cache.cleanup_interval": "1m" - } -} -``` -{% include copy-curl.html %} - ## Caching specific requests In addition to providing index-level or cluster-level settings for request cache, you can also cache specific search requests selectively by setting the `request_cache` query parameter to `true`: From dc1995acba775520b6c9ad4796982091b1dff309 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:39:41 -0400 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- .../configuring-opensearch/index-settings.md | 2 +- _search-plugins/caching/request-cache.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_install-and-configure/configuring-opensearch/index-settings.md b/_install-and-configure/configuring-opensearch/index-settings.md index 2e313cc1f4..34b1829b78 100644 --- a/_install-and-configure/configuring-opensearch/index-settings.md +++ b/_install-and-configure/configuring-opensearch/index-settings.md @@ -17,7 +17,7 @@ To learn more about static and dynamic settings, see [Configuring OpenSearch]({{ There are two types of cluster settings: -- [Static cluster-level index settings](#static-cluster-level-index-settings) are settings that you cannot update while the cluster is up. To update a static setting, you must stop the cluster, update the setting, and then restart the cluster. +- [Static cluster-level index settings](#static-cluster-level-index-settings) are settings that you cannot update while the cluster is running. To update a static setting, you must stop the cluster, update the setting, and then restart the cluster. - [Dynamic cluster-level index settings](#dynamic-cluster-level-index-settings) are settings that you can update at any time. ### Static cluster-level index settings diff --git a/_search-plugins/caching/request-cache.md b/_search-plugins/caching/request-cache.md index 9a4f40d8ea..124152300b 100644 --- a/_search-plugins/caching/request-cache.md +++ b/_search-plugins/caching/request-cache.md @@ -8,7 +8,7 @@ nav_order: 5 # Index request cache -The index request cache in OpenSearch 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 the load on the cluster 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 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. @@ -17,7 +17,7 @@ Search requests with `size=0` are cached in the request cache by default. Search ## Configuring request caching -You can configure index request cache by setting the parameters in the `opensearch.yml` configuration file or using the REST API. For more information, see [Index settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index-settings/). +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]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index-settings/). ### Settings @@ -43,7 +43,7 @@ PUT /my_index/_settings ## Caching specific requests -In addition to providing index-level or cluster-level settings for request cache, you can also cache specific search requests selectively by setting the `request_cache` query parameter to `true`: +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`: ```json GET /students/_search?request_cache=true @@ -59,11 +59,11 @@ GET /students/_search?request_cache=true ## Monitoring the request cache -Monitoring cache usage and performance is crucial for maintaining an efficient caching strategy. OpenSearch provides several APIs to help monitor the 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]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/nodes-stats/) returns cache statistics for all nodes in the cluster: +The [Nodes Stats API]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/nodes-stats/) returns cache statistics for all nodes in a cluster: ```json GET /_nodes/stats/indices/request_cache @@ -151,8 +151,8 @@ The response contains the request cache statistics: ## Best practices -When using index request cache, consider the following 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 they can benefit from caching. +- **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. \ No newline at end of file