|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Shard stores |
| 4 | +parent: Cluster APIs |
| 5 | +nav_order: 70 |
| 6 | +--- |
| 7 | + |
| 8 | +# Shard stores |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +## Endpoints |
| 13 | +```json |
| 14 | +GET /_shard_stores |
| 15 | +GET /{index}/_shard_stores |
| 16 | +``` |
| 17 | + |
| 18 | +## Path parameters |
| 19 | + |
| 20 | +The following table lists the available path parameters. All path parameters are optional. |
| 21 | + |
| 22 | +| Parameter | Data type | Description | |
| 23 | +| :--- | :--- | :--- | |
| 24 | +| `index` | List or String | List of data streams, indexes, and aliases used to limit the request. | |
| 25 | + |
| 26 | +## Query parameters |
| 27 | + |
| 28 | +The following table lists the available query parameters. All query parameters are optional. |
| 29 | + |
| 30 | +| Parameter | Data type | Description | Default | |
| 31 | +| `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` | |
| 32 | +| `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. <br> Valid values are: <br> - `all`: Match any index, including hidden ones. <br> - `closed`: Match closed, non-hidden indexes. <br> - `hidden`: Match hidden indexes. Must be combined with open, closed, or both. <br> - `none`: Wildcard expressions are not accepted. <br> - `open`: Match open, non-hidden indexes. | `open` | |
| 33 | +| `ignore_unavailable` | Boolean | If `true`, missing or closed indexes are not included in the response. | `false` | |
| 34 | +| `status` | List or String | List of shard health statuses used to limit the request. <br> Valid values are: <br> - `all`: Return all shards, regardless of health status. <br> - `green`: The primary shard and all replica shards are assigned. <br> - `red`: The primary shard is unassigned. <br> - `yellow`: One or more replica shards are unassigned. | `yellow,red` | |
| 35 | + |
| 36 | +## Example |
| 37 | + |
| 38 | +Create an index with multiple primary shards on a single-node cluster: |
| 39 | + |
| 40 | +```json |
| 41 | +PUT /logs-shardstore |
| 42 | +{ |
| 43 | + "settings": { |
| 44 | + "number_of_shards": 2, |
| 45 | + "number_of_replicas": 0 |
| 46 | + }, |
| 47 | + "mappings": { |
| 48 | + "properties": { |
| 49 | + "timestamp": { "type": "date" }, |
| 50 | + "message": { "type": "text" } |
| 51 | + } |
| 52 | + } |
| 53 | +} |
| 54 | +``` |
| 55 | +{% include copy-curl.html %} |
| 56 | + |
| 57 | +Index a document: |
| 58 | + |
| 59 | +```json |
| 60 | +POST /logs-shardstore/_doc |
| 61 | +{ |
| 62 | + "timestamp": "2025-06-20T12:00:00Z", |
| 63 | + "message": "Log message 1" |
| 64 | +} |
| 65 | +``` |
| 66 | +{% include copy-curl.html %} |
| 67 | + |
| 68 | +Get shard store status for the `logs-shardstore` index: |
| 69 | + |
| 70 | +```json |
| 71 | +GET /logs-shardstore/_shard_stores?status=all |
| 72 | +``` |
| 73 | +{% include copy-curl.html %} |
| 74 | + |
| 75 | +## Example response |
| 76 | + |
| 77 | +The response lists the stores that were assigned to each shard. If a shard has no assigned stores, it is marked `unassigned`: |
| 78 | + |
| 79 | +```json |
| 80 | +{ |
| 81 | + "indices": { |
| 82 | + "logs-shardstore": { |
| 83 | + "shards": { |
| 84 | + "0": { |
| 85 | + "stores": [ |
| 86 | + { |
| 87 | + "UFyVYVMCSDOObiRwPxSW5w": { |
| 88 | + "name": "opensearch-node1", |
| 89 | + "ephemeral_id": "vkSB_-M7QVyFXvgda6oRZg", |
| 90 | + "transport_address": "172.19.0.2:9300", |
| 91 | + "attributes": { |
| 92 | + "shard_indexing_pressure_enabled": "true" |
| 93 | + } |
| 94 | + }, |
| 95 | + "allocation_id": "PEM5YjEWSz-jJEj-Not6Aw", |
| 96 | + "allocation": "primary" |
| 97 | + } |
| 98 | + ] |
| 99 | + }, |
| 100 | + "1": { |
| 101 | + "stores": [] |
| 102 | + } |
| 103 | + } |
| 104 | + } |
| 105 | + } |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +## Response body fields |
| 110 | + |
| 111 | +The following table lists all response body fields. |
| 112 | + |
| 113 | +| Field | Data type | Description| |
| 114 | +| `indices` | Object| Contains shard store information for each index. | |
| 115 | +| `indices.<index>.shards`| Object| Contains store data for each shard in the index. | |
| 116 | +| `shards.<shard_id>.stores`| Array | A list of store entries for the shard.| |
| 117 | +| `stores[n].<node_id>` | Object| Node metadata, including name, transport address, and attributes. | |
| 118 | +| `stores[n].allocation`| String| The shard role on this node (`primary` or `replica`). | |
| 119 | +| `stores[n].allocation_id` | String| The unique allocation ID for this shard copy.| |
| 120 | +| `stores[n].store_exception` | Object (optional) | Stores exceptions encountered when reading the shard store. | |
| 121 | +| `stores[n].store_exception.type`| String| The type of exception.| |
| 122 | +| `stores[n].store_exception.reason`| String| The reason message for the exception.| |
0 commit comments