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

[[docs-multi-get]]
== Multi Get API

The Multi get API returns multiple documents based on an index, type,
(optional) and id (and possibly routing). The response includes a `docs` array
with all the fetched documents in order corresponding to the original multi-get
request (if there was a failure for a specific get, an object containing this
error is included in place in the response instead). The structure of a
successful get is similar in structure to a document provided by the
<<docs-get,get>> API.

Here is an example:

[source,js]
--------------------------------------------------
GET /_mget
{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "_doc",
            "_id" : "1"
        },
        {
            "_index" : "test",
            "_type" : "_doc",
            "_id" : "2"
        }
    ]
}
--------------------------------------------------
// CONSOLE

The `mget` endpoint can also be used against an index (in which case it
is not required in the body):

[source,js]
--------------------------------------------------
GET /test/_mget
{
    "docs" : [
        {
            "_type" : "_doc",
            "_id" : "1"
        },
        {
            "_type" : "_doc",
            "_id" : "2"
        }
    ]
}
--------------------------------------------------
// CONSOLE

And type:

[source,js]
--------------------------------------------------
GET /test/_doc/_mget
{
    "docs" : [
        {
            "_id" : "1"
        },
        {
            "_id" : "2"
        }
    ]
}
--------------------------------------------------
//CONSOLE

In which case, the `ids` element can directly be used to simplify the
request:

[source,js]
--------------------------------------------------
GET /test/_doc/_mget
{
    "ids" : ["1", "2"]
}
--------------------------------------------------
// CONSOLE

[float]
[[mget-source-filtering]]
=== Source filtering

By default, the `_source` field will be returned for every document (if stored).
Similar to the <<get-source-filtering,get>> API, you can retrieve only parts of
the `_source` (or not at all) by using the `_source` parameter. You can also use
the url parameters `_source`, `_source_includes`, and `_source_excludes` to specify defaults,
which will be used when there are no per-document instructions.

For example:

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


[float]
[[mget-fields]]
=== Fields

Specific stored fields can be specified to be retrieved per document to get, similar to the <<get-stored-fields,stored_fields>> parameter of the Get API.
For example:

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

Alternatively, you can specify the `stored_fields` parameter in the query string
as a default to be applied to all documents.

[source,js]
--------------------------------------------------
GET /test/_doc/_mget?stored_fields=field1,field2
{
    "docs" : [
        {
            "_id" : "1" <1>
        },
        {
            "_id" : "2",
            "stored_fields" : ["field3", "field4"] <2>
        }
    ]
}
--------------------------------------------------
// CONSOLE
<1> Returns `field1` and `field2`
<2> Returns `field3` and `field4`

[float]
[[mget-routing]]
=== Routing

You can also specify a routing value as a parameter:

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

In this example, document `test/_doc/2` will be fetched from the shard corresponding to routing key `key1` but
document `test/_doc/1` will be fetched from the shard corresponding to routing key `key2`.

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

See <<url-access-control>>.

[float]
[[multi-get-partial-responses]]
=== Partial responses
To ensure fast responses, the multi get API will respond with partial results if one or more shards fail. See <<shard-failures, Shard failures>> for more information.