From 6f932585069618b07328cab058ae0b73f1df2cc3 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Mon, 23 Jun 2025 12:36:06 +0100 Subject: [PATCH 1/4] adding docs for shard_stores api Signed-off-by: Anton Rubin --- _api-reference/cluster-api/shard-stores.md | 146 +++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 _api-reference/cluster-api/shard-stores.md diff --git a/_api-reference/cluster-api/shard-stores.md b/_api-reference/cluster-api/shard-stores.md new file mode 100644 index 00000000000..7da13aee6c9 --- /dev/null +++ b/_api-reference/cluster-api/shard-stores.md @@ -0,0 +1,146 @@ +--- +layout: default +title: Shard stores +parent: Cluster APIs +nav_order: 99 +--- + +# Shard stores + +The `_shard_stores` API provides information about the shard copies for one or more indices. This API helps to diagnose issues with unallocated shards by providing reasons why shards are unassigned and their current states. + + +## Endpoints +```json +GET /_shard_stores +GET /{index}/_shard_stores +``` + + + +## Path parameters + +The following table lists the available path parameters. All path parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | List or String | List of data streams, indexes, and aliases used to limit the request. | + + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | Default | +| `allow_no_indices` | Boolean | If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indexes. This behavior applies even if the request targets other open indexes. | `false` | +| `expand_wildcards` | List or String | Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | `open` | +| `ignore_unavailable` | Boolean | If `true`, missing or closed indexes are not included in the response. | `false` | +| `status` | List or String | List of shard health statuses used to limit the request.
Valid values are:
- `all`: Return all shards, regardless of health status.
- `green`: The primary shard and all replica shards are assigned.
- `red`: The primary shard is unassigned.
- `yellow`: One or more replica shards are unassigned. | `yellow,red` | + + + +## Example + +Create an index on a single node cluster with multiple primary shards: + +```json +PUT /logs-shardstore +{ + "settings": { + "number_of_shards": 2, + "number_of_replicas": 0 + }, + "mappings": { + "properties": { + "timestamp": { "type": "date" }, + "message": { "type": "text" } + } + } +} +``` +{% include copy-curl.html %} + +Index a document: + +```json +POST /logs-shardstore/_doc +{ + "timestamp": "2025-06-20T12:00:00Z", + "message": "Log message 1" +} +``` +{% include copy-curl.html %} + +Get shard store status for index `logs-shardstore`: + +```json +GET /logs-shardstore/_shard_stores?status=all +``` +{% include copy-curl.html %} + +## Example response + +The response lists the stores that were assigned to each shard. Empty stores indicates `unassigned` shard: + +```json +{ + "indices": { + "logs-shardstore": { + "shards": { + "0": { + "stores": [ + { + "UFyVYVMCSDOObiRwPxSW5w": { + "name": "opensearch-node1", + "ephemeral_id": "vkSB_-M7QVyFXvgda6oRZg", + "transport_address": "172.19.0.2:9300", + "attributes": { + "shard_indexing_pressure_enabled": "true" + } + }, + "allocation_id": "PEM5YjEWSz-jJEj-Not6Aw", + "allocation": "primary" + } + ] + }, + "1": { + "stores": [] + } + } + } + } +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description| +| `indices` | Object| Contains shard store information for each index. | +| `indices..shards`| Object| Contains store data for each shard in the index. | +| `shards..stores`| Array | List of store entries for that shard.| +| `stores[n].` | Object| Node metadata including name, transport address, and attributes. | +| `stores[n].allocation`| String| Shard role on this node: `primary` or `replica`. | +| `stores[n].allocation_id` | String| Unique allocation ID for this shard copy.| +| `stores[n].store_exception` | Object (optional) | Details of any exception encountered when reading the shard store. | +| `stores[n].store_exception.type`| String| The type of exception.| +| `stores[n].store_exception.reason`| String| The reason message for the exception.| From 5dd850b4fcc0e9d8d45ef42000bc7c7226292658 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Mon, 23 Jun 2025 12:38:18 +0100 Subject: [PATCH 2/4] adding docs for shard_stores api Signed-off-by: Anton Rubin --- _api-reference/cluster-api/shard-stores.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/shard-stores.md b/_api-reference/cluster-api/shard-stores.md index 7da13aee6c9..dbe29a5b1e9 100644 --- a/_api-reference/cluster-api/shard-stores.md +++ b/_api-reference/cluster-api/shard-stores.md @@ -2,7 +2,7 @@ layout: default title: Shard stores parent: Cluster APIs -nav_order: 99 +nav_order: 70 --- # Shard stores From c0258ebd184de44073bc2f7f1a3367a064c254c3 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 30 Jun 2025 09:31:28 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: AntonEliatra --- _api-reference/cluster-api/shard-stores.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/_api-reference/cluster-api/shard-stores.md b/_api-reference/cluster-api/shard-stores.md index dbe29a5b1e9..8d1a62bfaf9 100644 --- a/_api-reference/cluster-api/shard-stores.md +++ b/_api-reference/cluster-api/shard-stores.md @@ -59,7 +59,7 @@ The following table lists the available query parameters. All query parameters a ## Example -Create an index on a single node cluster with multiple primary shards: +Create an index with multiple primary shards on a single-node cluster: ```json PUT /logs-shardstore @@ -89,7 +89,7 @@ POST /logs-shardstore/_doc ``` {% include copy-curl.html %} -Get shard store status for index `logs-shardstore`: +Get shard store status for the `logs-shardstore` index: ```json GET /logs-shardstore/_shard_stores?status=all @@ -98,7 +98,7 @@ GET /logs-shardstore/_shard_stores?status=all ## Example response -The response lists the stores that were assigned to each shard. Empty stores indicates `unassigned` shard: +The response lists the stores that were assigned to each shard. If a shard has no assigned stores, it is marked `unassigned`: ```json { @@ -137,10 +137,10 @@ The following table lists all response body fields. | Field | Data type | Description| | `indices` | Object| Contains shard store information for each index. | | `indices..shards`| Object| Contains store data for each shard in the index. | -| `shards..stores`| Array | List of store entries for that shard.| +| `shards..stores`| Array | A list of store entries for the shard.| | `stores[n].` | Object| Node metadata including name, transport address, and attributes. | -| `stores[n].allocation`| String| Shard role on this node: `primary` or `replica`. | -| `stores[n].allocation_id` | String| Unique allocation ID for this shard copy.| -| `stores[n].store_exception` | Object (optional) | Details of any exception encountered when reading the shard store. | +| `stores[n].allocation`| String| The shard role on this node (`primary` or `replica`). | +| `stores[n].allocation_id` | String| The unique allocation ID for this shard copy.| +| `stores[n].store_exception` | Object (optional) | Stores exceptions encountered when reading the shard store. | | `stores[n].store_exception.type`| String| The type of exception.| | `stores[n].store_exception.reason`| String| The reason message for the exception.| From 518e121752dfc03059be9e112747bbd2f9223b74 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 30 Jun 2025 19:47:34 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: AntonEliatra --- _api-reference/cluster-api/shard-stores.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_api-reference/cluster-api/shard-stores.md b/_api-reference/cluster-api/shard-stores.md index 8d1a62bfaf9..4b674d4cace 100644 --- a/_api-reference/cluster-api/shard-stores.md +++ b/_api-reference/cluster-api/shard-stores.md @@ -7,7 +7,7 @@ nav_order: 70 # Shard stores -The `_shard_stores` API provides information about the shard copies for one or more indices. This API helps to diagnose issues with unallocated shards by providing reasons why shards are unassigned and their current states. +The `_shard_stores` API provides information about the shard copies for one or more indexes. This API helps to diagnose issues with unallocated shards by indicating why shards are unassigned and providing their current states.