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

Multi GET API allows to get multiple documents based on an index, type
(optional) and id (and possibly routing). The response includes a `docs`
array with all the fetched documents, each element similar in structure
to a document provided by the <<docs-get,get>>
API. Here is an example:

[source,js]
--------------------------------------------------
curl 'localhost:9200/_mget' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1"
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2"
        }
    ]
}'
--------------------------------------------------

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

[source,js]
--------------------------------------------------
curl 'localhost:9200/test/_mget' -d '{
    "docs" : [
        {
            "_type" : "type",
            "_id" : "1"
        },
        {
            "_type" : "type",
            "_id" : "2"
        }
    ]
}'
--------------------------------------------------

And type:

[source,js]
--------------------------------------------------
curl 'localhost:9200/test/type/_mget' -d '{
    "docs" : [
        {
            "_id" : "1"
        },
        {
            "_id" : "2"
        }
    ]
}'
--------------------------------------------------

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

[source,js]
--------------------------------------------------
curl 'localhost:9200/test/type/_mget' -d '{
    "ids" : ["1", "2"]
}'
--------------------------------------------------

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

added[1.0.0.Beta1]

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_include` & `_source_exclude` to specify defaults,
which will be used when there are no per-document instructions.

For example:

[source,js]
--------------------------------------------------
curl 'localhost:9200/_mget' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1",
            "_source" : false
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2",
            "_source" : ["field3", "field4"]
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "3",
            "_source" : {
                "include": ["user"],
                "_exclude": ["user.location"]
            }
        }
    ]
}'
--------------------------------------------------


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

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

[source,js]
--------------------------------------------------
curl 'localhost:9200/_mget' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1",
            "fields" : ["field1", "field2"]
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2",
            "fields" : ["field3", "field4"]
        }
    ]
}'
--------------------------------------------------

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

You can specify also specify routing value as a parameter:

[source,js]
--------------------------------------------------
curl 'localhost:9200/_mget?routing=key1' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1",
            "_routing" : "key2"
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2"
        }
    ]
}'
--------------------------------------------------

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

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

See <<url-access-control>>
