187 lines
4.5 KiB
Plaintext
187 lines
4.5 KiB
Plaintext
[[indices-shards-stores]]
|
|
=== Index shard stores API
|
|
++++
|
|
<titleabbrev>Index shard stores</titleabbrev>
|
|
++++
|
|
|
|
Returns store information
|
|
about replica shards in one or more indices.
|
|
|
|
[source,console]
|
|
----
|
|
GET /twitter/_shard_stores
|
|
----
|
|
// TEST[setup:twitter]
|
|
|
|
|
|
[[index-shard-stores-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /<index>/_shard_stores`
|
|
|
|
`GET /_shard_stores`
|
|
|
|
|
|
[[index-shard-stores-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
Use the index shard stores API to return store information
|
|
about replica shards in one or more indices.
|
|
|
|
Returned information includes:
|
|
|
|
* The node on which each replica shard exists
|
|
* Allocation ID for each replica shard
|
|
* Unique ID for each replica shard
|
|
* Any errors encountered
|
|
while opening the shard index
|
|
or from an earlier failure
|
|
|
|
By default, the API only returns store information
|
|
for primary shards that are unassigned
|
|
or have one or more unassigned replica shards.
|
|
|
|
|
|
[[index-shard-stores-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
|
+
|
|
To retrieve information for all indices in the cluster,
|
|
use a value of `_all` or `*`
|
|
or omit this parameter.
|
|
|
|
|
|
[[index-shard-stores-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
|
+
|
|
Defaults to `true`.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
|
+
|
|
Defaults to `open`.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
|
|
|
`status`::
|
|
+
|
|
--
|
|
(Optional, string)
|
|
Comma-separated list of shard health statuses
|
|
used to limit the request.
|
|
|
|
Valid values include:
|
|
|
|
`green`::
|
|
The primary shard and all replica shards are assigned.
|
|
|
|
`yellow`::
|
|
One or more replica shards are unassigned.
|
|
|
|
`red`::
|
|
The primary shard is unassigned.
|
|
|
|
`all`::
|
|
Return all shards,
|
|
regardless of health status.
|
|
|
|
Defaults to `yellow,red`.
|
|
--
|
|
|
|
[[index-shard-stores-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
|
|
[[index-shard-stores-api-single-ex]]
|
|
===== Get shard store information for a specific index
|
|
|
|
[source,console]
|
|
----
|
|
GET /test/_shard_stores
|
|
----
|
|
// TEST[s/^/PUT test\n/]
|
|
|
|
|
|
[[index-shard-stores-api-multi-ex]]
|
|
===== Get shard store information for several indices
|
|
|
|
[source,console]
|
|
----
|
|
GET /test1,test2/_shard_stores
|
|
----
|
|
// TEST[s/^/PUT test1\nPUT test2\n/]
|
|
|
|
|
|
[[index-shard-stores-api-all-ex]]
|
|
===== Get shard store information for all indices
|
|
|
|
[source,console]
|
|
----
|
|
GET /_shard_stores
|
|
----
|
|
// TEST[continued]
|
|
|
|
|
|
[[index-shard-stores-api-health-ex]]
|
|
===== Get shard store information based on cluster health
|
|
|
|
You can use the `status` query parameter
|
|
to limit returned information based on shard health.
|
|
|
|
The following request only returns information
|
|
for assigned primary and replica shards.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_shard_stores?status=green
|
|
--------------------------------------------------
|
|
// TEST[setup:node]
|
|
// TEST[s/^/PUT my-index\n{"settings":{"number_of_shards":1, "number_of_replicas": 0}}\nPOST my-index\/test\?refresh\n{"test": "test"}\n/]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"my-index": {
|
|
"shards": {
|
|
"0": { <1>
|
|
"stores": [ <2>
|
|
{
|
|
"sPa3OgxLSYGvQ4oPs-Tajw": { <3>
|
|
"name": "node_t0",
|
|
"ephemeral_id" : "9NlXRFGCT1m8tkvYCMK-8A",
|
|
"transport_address": "local[1]",
|
|
"attributes": {}
|
|
},
|
|
"allocation_id": "2iNySv_OQVePRX-yaRH_lQ", <4>
|
|
"allocation" : "primary|replica|unused" <5>
|
|
"store_exception": ... <6>
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"store_exception": \.\.\.//]
|
|
// TESTRESPONSE[s/"sPa3OgxLSYGvQ4oPs-Tajw"/\$node_name/]
|
|
// TESTRESPONSE[s/: "[^"]*"/: $body.$_path/]
|
|
// TESTRESPONSE[s/"attributes": \{[^}]*\}/"attributes": $body.$_path/]
|
|
|
|
|
|
|
|
<1> The key is the corresponding shard id for the store information
|
|
<2> A list of store information for all copies of the shard
|
|
<3> The node information that hosts a copy of the store, the key
|
|
is the unique node id.
|
|
<4> The allocation id of the store copy
|
|
<5> The status of the store copy, whether it is used as a
|
|
primary, replica or not used at all
|
|
<6> Any exception encountered while opening the shard index or
|
|
from earlier engine failure
|