IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Multi Get API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Multi Get API

edit

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 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

edit

By 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_include & _source_exclude 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

edit

Specific 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"] 
        }
    ]
}

	Returns `field1` and `field2`
	Returns `field3` and `field4`

Routing

edit

You can also specify 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 fetch from shard corresponding to routing key key1 but document test/_doc/1 will be fetch from shard corresponding to routing key key2.

Security

edit

See URL-based access control

« Update By Query API Bulk API »