elasticsearch/docs/reference/docs/multi-get.asciidoc

[[docs-multi-get]]
=== Multi get (mget) API
++++
<titleabbrev>Multi get</titleabbrev>
++++

Retrieves multiple JSON documents by ID. 

[source,console]
--------------------------------------------------
GET /_mget
{
  "docs": [
    {
      "_index": "my-index-000001",
      "_id": "1"
    },
    {
      "_index": "my-index-000001",
      "_id": "2"
    }
  ]
}
--------------------------------------------------
// TEST[setup:my_index]

[[docs-multi-get-api-request]]
==== {api-request-title}

`GET /_mget`

`GET /<index>/_mget`

[[docs-multi-get-api-prereqs]]
==== {api-prereq-title}

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

[[docs-multi-get-api-desc]]
==== {api-description-title}

You use `mget` to retrieve multiple documents from one or more indices.
If you specify an index in the request URI, you only need to specify the document IDs in the request body.

[[mget-security]]
===== Security

See <<api-url-access-control>>.

[[multi-get-partial-responses]]
===== Partial responses

To ensure fast responses, the multi get API responds with partial results if one or more shards fail. 
See <<shard-failures, Shard failures>> for more information.

[[docs-multi-get-api-path-params]]
==== {api-path-parms-title}

`<index>`::
(Optional, string) Name of the index to retrieve documents from when `ids` are specified,
or when a document in the `docs` array does not specify an index.

[[docs-multi-get-api-query-params]]
==== {api-query-parms-title}

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

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

`refresh`::
(Optional, Boolean) If `true`, the request refreshes relevant shards before
retrieving documents. Defaults to `false`.

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

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

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

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

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

[[docs-multi-get-api-request-body]]
==== {api-request-body-title}

`docs`::
(Optional, array) The documents you want to retrieve.
Required if no index is specified in the request URI.
You can specify the following attributes for each
document:
+
--
`_id`::
(Required, string) The unique document ID.

`_index`::
(Optional, string)
The index that contains the document.
Required if no index is specified in the request URI.

`routing`::
(Optional, string) The key for the primary shard the document resides on.
Required if routing is used during indexing.

`_source`::
(Optional, Boolean) If `false`,  excludes all `_source` fields. Defaults to `true`.
`source_include`:::
(Optional, array) The fields to extract and return from the `_source` field.
`source_exclude`:::
(Optional, array) The fields to exclude from the returned `_source` field.

`_stored_fields`::
(Optional, array) The stored fields you want to retrieve.
--

`ids`::
(Optional, array) The IDs of the documents you want to retrieve.
Allowed when the index is specified in the request URI.

[[multi-get-api-response-body]]
==== {api-response-body-title}

The response includes a `docs` array that contains the documents in the order specified in the request. 
The structure of the returned documents is similar to that returned by the <<docs-get,get>> API.
If there is a failure getting a particular document, the error is included in place of the document. 

[[docs-multi-get-api-example]]
==== {api-examples-title}

[[mget-ids]]
===== Get documents by ID

If you specify an index in the request URI, only the document IDs are required in the request body:

[source,console]
--------------------------------------------------
GET /my-index-000001/_mget
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ]
}
--------------------------------------------------
// TEST[setup:my_index]

You can use the `ids` element to simplify the request:

[source,console]
--------------------------------------------------
GET /my-index-000001/_mget
{
  "ids" : ["1", "2"]
}
--------------------------------------------------
// TEST[setup:my_index]

[[mget-source-filtering]]
===== Filter source fields

By default, the `_source` field is returned for every document (if stored). 
Use the `_source` and `_source_include` or `source_exclude` attributes to 
filter what fields are returned for a particular document.
You can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the
request URI to specify the defaults to use when there are no per-document instructions.

For example, the following request sets `_source` to false for document 1 to exclude the
source entirely, retrieves `field3` and `field4` from document 2, and retrieves the `user` field
from document 3 but filters out the `user.location` field.

[source,console]
--------------------------------------------------
GET /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}
--------------------------------------------------

[[mget-fields]]
===== Get stored fields

Use the `stored_fields` attribute to specify the set of stored fields you want
to retrieve. Any requested fields that are not stored are ignored. 
You can include the `stored_fields` query parameter in the request URI to specify the defaults 
to use when there are no per-document instructions. 

For example, the following request retrieves `field1` and `field2` from document 1, and
`field3` and `field4` from document 2:

[source,console]
--------------------------------------------------
GET /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "stored_fields": [ "field1", "field2" ]
    },
    {
      "_index": "test",
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}
--------------------------------------------------

The following request retrieves `field1` and `field2` from all documents by default.
These default fields are returned for document 1, but 
overridden to return `field3` and `field4` for document 2.

[source,console]
--------------------------------------------------
GET /test/_mget?stored_fields=field1,field2
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}
--------------------------------------------------

[[mget-routing]]
===== Specify document routing

If routing is used during indexing, you need to specify the routing value to retrieve documents. 
For example, the following request fetches `test/_doc/2`  from the shard corresponding to routing key `key1`,
and fetches `test/_doc/1` from the shard corresponding to routing key `key2`.

[source,console]
--------------------------------------------------
GET /_mget?routing=key1
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "routing": "key2"
    },
    {
      "_index": "test",
      "_id": "2"
    }
  ]
}
--------------------------------------------------