Multi Get API
editMulti Get API
editThe 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
get API.
Here is an example:
GET /_mget { "docs" : [ { "_index" : "test", "_type" : "_doc", "_id" : "1" }, { "_index" : "test", "_type" : "_doc", "_id" : "2" } ] }
The mget
endpoint can also be used against an index (in which case it
is not required in the body):
GET /test/_mget { "docs" : [ { "_type" : "_doc", "_id" : "1" }, { "_type" : "_doc", "_id" : "2" } ] }
And type:
GET /test/_doc/_mget { "docs" : [ { "_id" : "1" }, { "_id" : "2" } ] }
In which case, the ids
element can directly be used to simplify the
request:
GET /test/_doc/_mget { "ids" : ["1", "2"] }
Source filtering
editBy default, the _source
field will be returned for every document (if stored).
Similar to the 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:
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"] } } ] }
Fields
editSpecific stored fields can be specified to be retrieved per document to get, similar to the stored_fields parameter of the Get API. For example:
GET /_mget { "docs" : [ { "_index" : "test", "_type" : "_doc", "_id" : "1", "stored_fields" : ["field1", "field2"] }, { "_index" : "test", "_type" : "_doc", "_id" : "2", "stored_fields" : ["field3", "field4"] } ] }
Alternatively, you can specify the stored_fields
parameter in the query string
as a default to be applied to all documents.
GET /test/_doc/_mget?stored_fields=field1,field2 { "docs" : [ { "_id" : "1" }, { "_id" : "2", "stored_fields" : ["field3", "field4"] } ] }
Routing
editYou can also specify a routing value as a parameter:
GET /_mget?routing=key1 { "docs" : [ { "_index" : "test", "_type" : "_doc", "_id" : "1", "routing" : "key2" }, { "_index" : "test", "_type" : "_doc", "_id" : "2" } ] }
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
.
Security
editPartial responses
editTo ensure fast responses, the multi get API will respond with partial results if one or more shards fail. See Shard failures for more information.