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

[[search-shards]]
=== Search shards API
++++
<titleabbrev>Search shards</titleabbrev>
++++

Returns the indices and shards that a search request would be executed against.

[source,console]
--------------------------------------------------
GET /my-index-000001/_search_shards
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n{"settings":{"index.number_of_shards":5}}\n/]


[[search-shards-api-request]]
==== {api-request-title}

`GET /<target>/_search_shards`

[[search-shards-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
for the target data stream, index, or alias.

[[search-shards-api-desc]]
==== {api-description-title}

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.


[[search-shards-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) Comma-separated list of data streams, indices, and aliases to
search. Supports wildcards (`*`). To search all data streams and indices, omit
this parameter or use `*` or `_all`.

[[search-shards-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
--
Defaults to `open`.
--

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=preference]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]


[[search-shards-api-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
GET /my-index-000001/_search_shards
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n{"settings":{"index.number_of_shards":5}}\n/]

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  "nodes": ...,
  "indices" : {
    "my-index-000001": { }
  },
  "shards": [
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 0,
        "state": "STARTED",
        "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ],
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 1,
        "state": "STARTED",
        "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ],
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 2,
        "state": "STARTED",
        "allocation_id": {"id":"Nwl0wbMBTHCWjEEbGYGapg"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ],
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 3,
        "state": "STARTED",
        "allocation_id": {"id":"bU_KLGJISbW0RejwnwDPKw"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ],
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 4,
        "state": "STARTED",
        "allocation_id": {"id":"DMs7_giNSwmdqVukF7UydA"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ]
  ]
}
--------------------------------------------------
// 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/]

Specifying the same request, this time with a routing value:

[source,console]
--------------------------------------------------
GET /my-index-000001/_search_shards?routing=foo,bar
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n{"settings":{"index.number_of_shards":5}}\n/]

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  "nodes": ...,
  "indices" : {
      "my-index-000001": { }
  },
  "shards": [
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 2,
        "state": "STARTED",
        "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ],
    [
      {
        "index": "my-index-000001",
        "node": "JklnKbD7Tyqi9TP3_Q_tBg",
        "relocating_node": null,
        "primary": true,
        "shard": 3,
        "state": "STARTED",
        "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
        "relocation_failure_info" : {
          "failed_attempts" : 0
        }
      }
    ]
  ]
}
--------------------------------------------------
// 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/]

Because of the specified routing values,
the search is only executed against two of the shards.