Multi get (mget) API
editMulti get (mget) API
editRetrieves multiple JSON documents by ID.
GET /_mget { "docs" : [ { "_index" : "twitter", "_id" : "1" }, { "_index" : "twitter", "_id" : "2" } ] }
Description
editYou 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.
Security
editPartial responses
editTo ensure fast responses, the multi get API responds with partial results if one or more shards fail. See Shard failures for more information.
Path parameters
edit-
<index>
-
(Optional, string) Name of the index to retrieve documents from when
ids
are specified, or when a document in thedocs
array does not specify an index.
Query parameters
edit-
preference
- (Optional, string) Specifies the node or shard the operation should be performed on. Random by default.
-
realtime
-
(Optional, boolean) If
true
, the request is real-time as opposed to near-real-time. Defaults totrue
. See Realtime. -
refresh
-
(Optional, Boolean) If
true
, the request refreshes relevant shards before retrieving documents. Defaults tofalse
. -
routing
- (Optional, string) Target the specified primary shard.
-
stored_fields
-
(Optional, boolean) If
true
, retrieves the document fields stored in the index rather than the document_source
. Defaults tofalse
. -
_source
-
(Optional, string) True or false to return the
_source
field or not, or a list of fields to return. -
_source_excludes
-
(Optional, string) A list of fields to exclude from the returned
_source
field. -
_source_includes
-
(Optional, string) A list of fields to extract and return from the
_source
field.
Request body
edit-
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 totrue
.-
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.
Response body
editThe 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 get API.
If there is a failure getting a particular document, the error is included in place of the document.
Examples
editGet documents by ID
editIf you specify an index in the request URI, only the document IDs are required in the request body:
GET /twitter/_mget { "docs" : [ { "_type" : "_doc", "_id" : "1" }, { "_type" : "_doc", "_id" : "2" } ] }
And type:
GET /test/_doc/_mget { "docs" : [ { "_id" : "1" }, { "_id" : "2" } ] }
You can use the ids
element to simplify the request:
GET /twitter/_mget { "ids" : ["1", "2"] }
Filter source fields
editBy 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.
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"] } } ] }
Get stored fields
editUse 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:
GET /_mget { "docs" : [ { "_index" : "test", "_type" : "_doc", "_id" : "1", "stored_fields" : ["field1", "field2"] }, { "_index" : "test", "_type" : "_doc", "_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.
GET /test/_doc/_mget?stored_fields=field1,field2 { "docs" : [ { "_id" : "1" }, { "_id" : "2", "stored_fields" : ["field3", "field4"] } ] }
Specify document routing
editIf 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
.
GET /_mget?routing=key1 { "docs" : [ { "_index" : "test", "_type" : "_doc", "_id" : "1", "routing" : "key2" }, { "_index" : "test", "_type" : "_doc", "_id" : "2" } ] }