Get multiple documents

POST also GET /{index}/_mget
POST also GET /_mget

Get multiple JSON documents by ID 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. To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.

Filter source fields

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

Get stored fields

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

Required authorization

Index privileges: read

Path Parameters

index string IndexName optional

Name of the index to retrieve documents from when ids are specified, or when a document in the docs array does not specify an index.

Leave it out to use /_mget.

Query Parameters

preference string: Specifies the node or shard the operation should be performed on. Random by default.
realtime boolean · default: true: If true, the request is real-time as opposed to near-real-time.
refresh boolean · default: false: If true, the request refreshes relevant shards before retrieving documents.
routing union Routing: Custom value used to route operations to a specific shard. Not allowed when index.slice.enabled is true for the target index; use _slice instead.; One of: string or string[]
_source union SourceConfigParam: True or false to return the _source field or not, or a list of fields to return.; One of: boolean or Fields
_source_excludes union Fields: A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.; One of: Field or Field[]
_source_includes union Fields: A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.; One of: Field or Field[]
stored_fields string Fields · default: false: If true, retrieves the document fields stored in the index rather than the document _source.

Request

Response

application/json

docs [] union ResponseItem required: The 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.; One of:

Examples

Run POST /my-index-000001/_mget. When you specify an index in the request URI, only the document IDs are required in the request body.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /my-index-000001/_mget
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ]
}

JavaScript Elasticsearch JavaScript Client

const response = await client.mget({
  index: "my-index-000001",
  docs: [
    {
      _id: "1",
    },
    {
      _id: "2",
    },
  ],
});

Python Elasticsearch Python Client

resp = client.mget(
    index="my-index-000001",
    docs=[
        {
            "_id": "1"
        },
        {
            "_id": "2"
        }
    ],
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_mget" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": [
      {
        "_id": "1"
      },
      {
        "_id": "2"
      }
    ]
  }'

Java Elasticsearch Java Client

client.mget(m -> m
    .docs(List.of(MultiGetOperation.of(mu -> mu
            .id("1")
        ),MultiGetOperation.of(mu -> mu
            .id("2")
        )))
    .index("my-index-000001")
);

C# Elasticsearch .NET Client

var response = await client
    .MultiGetAsync<MyDocument>(d1 => d1
        .Index("my-index-000001")
        .Docs(d2 => d2
            .Id("1"), d2 => d2
            .Id("2")
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->mget([
    "index" => "my-index-000001",
    "body" => [
        "docs" => array(
            [
                "_id" => "1",
            ],
            [
                "_id" => "2",
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.mget(
  index: "my-index-000001",
  body: {
    "docs": [
      {
        "_id": "1"
      },
      {
        "_id": "2"
      }
    ]
  }
)

Response

No example

Run POST /_mget. This request sets _source to false for document 1 to exclude the source entirely. It retrieves field3 and field4 from document 2. It retrieves the user field from document 3 but filters out the user.location field.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_mget" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}'

Response

No example

Run POST /_mget. This request retrieves field1 and field2 from document 1 and field3 and field4 from document 2.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "stored_fields": [ "field1", "field2" ]
    },
    {
      "_index": "test",
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_mget" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "stored_fields": [ "field1", "field2" ]
    },
    {
      "_index": "test",
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}'

Response

No example

Run POST /_mget?routing=key1. If routing is used during indexing, you need to specify the routing value to retrieve documents. This request fetches test/_doc/2 from the shard corresponding to routing key key1. It fetches test/_doc/1 from the shard corresponding to routing key key2.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /_mget?routing=key1
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "routing": "key2"
    },
    {
      "_index": "test",
      "_id": "2"
    }
  ]
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_mget?routing=key1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "routing": "key2"
    },
    {
      "_index": "test",
      "_id": "2"
    }
  ]
}'

Response

No example

Required authorization

Path Parameters

Query Parameters { preference , realtime , refresh , routing , _source , _source_excludes , _source_includes , stored_fields , }

Request { docs , ids , }

Response

Query Parameters

Request