OpenSearch/docs/reference/search/search-shards.asciidoc

[[search-shards]]
== Search Shards API

The search shards api returns the indices and shards that a search request would
be executed against. This can give useful feedback for working out issues or
planning optimizations with routing and shard preferences.

The `index` and `type` parameters may be single values, or comma-separated.

[float]
=== Usage

Full example:

[source,js]
--------------------------------------------------
GET /twitter/_search_shards
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT twitter\n/]

This will yield the following result:

[source,js]
--------------------------------------------------
{
  "nodes": ...,
  "shards": [
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 0,
        "state": "STARTED",
        "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
        "relocating_node": null
      }
    ],
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 1,
        "state": "STARTED",
        "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
        "relocating_node": null
      }
    ],
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 2,
        "state": "STARTED",
        "allocation_id": {"id":"Nwl0wbMBTHCWjEEbGYGapg"},
        "relocating_node": null
      }
    ],
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 3,
        "state": "STARTED",
        "allocation_id": {"id":"bU_KLGJISbW0RejwnwDPKw"},
        "relocating_node": null
      }
    ],
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 4,
        "state": "STARTED",
        "allocation_id": {"id":"DMs7_giNSwmdqVukF7UydA"},
        "relocating_node": null
      }
    ]
  ]
}
--------------------------------------------------
// TESTRESPONSE[s/"nodes": ...,/"nodes": $body.nodes,/]
// TESTRESPONSE[s/JklnKbD7Tyqi9TP3_Q_tBg/$body.shards.0.0.node/]
// TESTRESPONSE[s/0TvkCyF7TAmM1wHP4a42-A/$body.shards.0.0.allocation_id.id/]
// TESTRESPONSE[s/fMju3hd1QHWmWrIgFnI4Ww/$body.shards.1.0.allocation_id.id/]
// TESTRESPONSE[s/Nwl0wbMBTHCWjEEbGYGapg/$body.shards.2.0.allocation_id.id/]
// TESTRESPONSE[s/bU_KLGJISbW0RejwnwDPKw/$body.shards.3.0.allocation_id.id/]
// TESTRESPONSE[s/DMs7_giNSwmdqVukF7UydA/$body.shards.4.0.allocation_id.id/]

And specifying the same request, this time with a routing value:

[source,js]
--------------------------------------------------
GET /twitter/_search_shards?routing=foo,baz
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT twitter\n/]

This will yield the following result:

[source,js]
--------------------------------------------------
{
  "nodes": ...,
  "shards": [
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 0,
        "state": "STARTED",
        "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
        "relocating_node": null
      }
    ],
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 1,
        "state": "STARTED",
        "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
        "relocating_node": null
      }
    ]
  ]
}
--------------------------------------------------
// TESTRESPONSE[s/"nodes": ...,/"nodes": $body.nodes,/]
// TESTRESPONSE[s/JklnKbD7Tyqi9TP3_Q_tBg/$body.shards.0.0.node/]
// TESTRESPONSE[s/0TvkCyF7TAmM1wHP4a42-A/$body.shards.0.0.allocation_id.id/]
// TESTRESPONSE[s/fMju3hd1QHWmWrIgFnI4Ww/$body.shards.1.0.allocation_id.id/]

This time the search will only be executed against two of the shards, because
routing values have been specified.

[float]
=== All parameters:

[horizontal]
`routing`::
    A comma-separated list of routing values to take into account when
    determining which shards a request would be executed against.

`preference`::
    Controls a `preference` of which shard replicas to execute the search
    request on. By default, the operation is randomized between the shard
    replicas. See the link:search-request-preference.html[preference]
    documentation for a list of all acceptable values.

`local`::
    A boolean value whether to read the cluster state locally in order to
    determine where shards are allocated instead of using the Master node's
    cluster state.