[[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. When filtered aliases
are used, the filter is returned as part of the `indices` section [5.1.0] Added in 5.1.0.

The `index` may be a single value, or comma-separated.

[float]
==== Usage

Full example:

[source,js]
--------------------------------------------------
GET /twitter/_search_shards
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":5}}\n/]

This will yield the following result:

[source,js]
--------------------------------------------------
{
  "nodes": ...,
  "indices" : {
    "twitter": { }
  },
  "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,bar
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":5}}\n/]

This will yield the following result:

[source,js]
--------------------------------------------------
{
  "nodes": ...,
  "indices" : {
      "twitter": { }
  },
  "shards": [
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 2,
        "state": "STARTED",
        "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
        "relocating_node": null
      }
    ],
    [
      {
        "index": "twitter",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "primary": true,
        "shard": 3,
        "state": "STARTED",
        "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
        "relocating_node": null
      }
    ]
  ]
}
--------------------------------------------------
// TESTRESPONSE[s/"nodes": ...,/"nodes": $body.nodes,/]
// TESTRESPONSE[s/JklnKbD7Tyqi9TP3_Q_tBg/$body.shards.1.0.node/]
// TESTRESPONSE[s/0TvkCyF7TAmM1wHP4a42-A/$body.shards.1.0.allocation_id.id/]
// TESTRESPONSE[s/fMju3hd1QHWmWrIgFnI4Ww/$body.shards.0.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-body.html#request-body-search-preference[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.