Multi get (mget) API

Multi get (mget) API

New API reference

For the most up-to-date API details, refer to Document APIs.

Retrieves multiple JSON documents by ID.

  1. resp = client.mget(
  2.     docs=[
  3.         {
  4.             "_index": "my-index-000001",
  5.             "_id": "1"
  6.         },
  7.         {
  8.             "_index": "my-index-000001",
  9.             "_id": "2"
  10.         }
  11.     ],
  12. )
  13. print(resp)
  1. response = client.mget(
  2.   body: {
  3.     docs: [
  4.       {
  5.         _index: 'my-index-000001',
  6.         _id: '1'
  7.       },
  8.       {
  9.         _index: 'my-index-000001',
  10.         _id: '2'
  11.       }
  12.     ]
  13.   }
  14. )
  15. puts response
  1. const response = await client.mget({
  2.   docs: [
  3.     {
  4.       _index: "my-index-000001",
  5.       _id: "1",
  6.     },
  7.     {
  8.       _index: "my-index-000001",
  9.       _id: "2",
  10.     },
  11.   ],
  12. });
  13. console.log(response);
  1. GET /_mget
  2. {
  3.   "docs": [
  4.     {
  5.       "_index": "my-index-000001",
  6.       "_id": "1"
  7.     },
  8.     {
  9.       "_index": "my-index-000001",
  10.       "_id": "2"
  11.     }
  12.   ]
  13. }

Request

GET /_mget

GET /<index>/_mget

Prerequisites

  • If the Elasticsearch security features are enabled, you must have the read index privilege for the target index or index alias.

Description

You 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

See URL-based access control.

Partial responses

To 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

<index>

(Optional, string) 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.

Query parameters

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 to true. See Realtime.

refresh

(Optional, Boolean) If true, the request refreshes relevant shards before retrieving documents. Defaults to false.

routing

(Optional, string) Custom value used to route operations to a specific shard.

stored_fields

(Optional, string) A comma-separated list of stored fields to include in the response.

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

If the _source parameter is false, this parameter is ignored.

_source_includes

(Optional, string) 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.

Request body

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 to true.

    • 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

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.

Examples

Get documents by ID

If you specify an index in the request URI, only the document IDs are required in the request body:

  1. resp = client.mget(
  2.     index="my-index-000001",
  3.     docs=[
  4.         {
  5.             "_id": "1"
  6.         },
  7.         {
  8.             "_id": "2"
  9.         }
  10.     ],
  11. )
  12. print(resp)
  1. response = client.mget(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     docs: [
  5.       {
  6.         _id: '1'
  7.       },
  8.       {
  9.         _id: '2'
  10.       }
  11.     ]
  12.   }
  13. )
  14. puts response
  1. const response = await client.mget({
  2.   index: "my-index-000001",
  3.   docs: [
  4.     {
  5.       _id: "1",
  6.     },
  7.     {
  8.       _id: "2",
  9.     },
  10.   ],
  11. });
  12. console.log(response);
  1. GET /my-index-000001/_mget
  2. {
  3.   "docs": [
  4.     {
  5.       "_id": "1"
  6.     },
  7.     {
  8.       "_id": "2"
  9.     }
  10.   ]
  11. }

You can use the ids element to simplify the request:

  1. resp = client.mget(
  2.     index="my-index-000001",
  3.     ids=[
  4.         "1",
  5.         "2"
  6.     ],
  7. )
  8. print(resp)
  1. response = client.mget(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     ids: [
  5.       '1',
  6.       '2'
  7.     ]
  8.   }
  9. )
  10. puts response
  1. const response = await client.mget({
  2.   index: "my-index-000001",
  3.   ids: ["1", "2"],
  4. });
  5. console.log(response);
  1. GET /my-index-000001/_mget
  2. {
  3.   "ids" : ["1", "2"]
  4. }

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.

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.

  1. resp = client.mget(
  2.     docs=[
  3.         {
  4.             "_index": "test",
  5.             "_id": "1",
  6.             "_source": False
  7.         },
  8.         {
  9.             "_index": "test",
  10.             "_id": "2",
  11.             "_source": [
  12.                 "field3",
  13.                 "field4"
  14.             ]
  15.         },
  16.         {
  17.             "_index": "test",
  18.             "_id": "3",
  19.             "_source": {
  20.                 "include": [
  21.                     "user"
  22.                 ],
  23.                 "exclude": [
  24.                     "user.location"
  25.                 ]
  26.             }
  27.         }
  28.     ],
  29. )
  30. print(resp)
  1. response = client.mget(
  2.   body: {
  3.     docs: [
  4.       {
  5.         _index: 'test',
  6.         _id: '1',
  7.         _source: false
  8.       },
  9.       {
  10.         _index: 'test',
  11.         _id: '2',
  12.         _source: [
  13.           'field3',
  14.           'field4'
  15.         ]
  16.       },
  17.       {
  18.         _index: 'test',
  19.         _id: '3',
  20.         _source: {
  21.           include: [
  22.             'user'
  23.           ],
  24.           exclude: [
  25.             'user.location'
  26.           ]
  27.         }
  28.       }
  29.     ]
  30.   }
  31. )
  32. puts response
  1. const response = await client.mget({
  2.   docs: [
  3.     {
  4.       _index: "test",
  5.       _id: "1",
  6.       _source: false,
  7.     },
  8.     {
  9.       _index: "test",
  10.       _id: "2",
  11.       _source: ["field3", "field4"],
  12.     },
  13.     {
  14.       _index: "test",
  15.       _id: "3",
  16.       _source: {
  17.         include: ["user"],
  18.         exclude: ["user.location"],
  19.       },
  20.     },
  21.   ],
  22. });
  23. console.log(response);
  1. GET /_mget
  2. {
  3.   "docs": [
  4.     {
  5.       "_index": "test",
  6.       "_id": "1",
  7.       "_source": false
  8.     },
  9.     {
  10.       "_index": "test",
  11.       "_id": "2",
  12.       "_source": [ "field3", "field4" ]
  13.     },
  14.     {
  15.       "_index": "test",
  16.       "_id": "3",
  17.       "_source": {
  18.         "include": [ "user" ],
  19.         "exclude": [ "user.location" ]
  20.       }
  21.     }
  22.   ]
  23. }

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.

For example, the following request retrieves field1 and field2 from document 1, and field3 and field4 from document 2:

  1. resp = client.mget(
  2.     docs=[
  3.         {
  4.             "_index": "test",
  5.             "_id": "1",
  6.             "stored_fields": [
  7.                 "field1",
  8.                 "field2"
  9.             ]
  10.         },
  11.         {
  12.             "_index": "test",
  13.             "_id": "2",
  14.             "stored_fields": [
  15.                 "field3",
  16.                 "field4"
  17.             ]
  18.         }
  19.     ],
  20. )
  21. print(resp)
  1. response = client.mget(
  2.   body: {
  3.     docs: [
  4.       {
  5.         _index: 'test',
  6.         _id: '1',
  7.         stored_fields: [
  8.           'field1',
  9.           'field2'
  10.         ]
  11.       },
  12.       {
  13.         _index: 'test',
  14.         _id: '2',
  15.         stored_fields: [
  16.           'field3',
  17.           'field4'
  18.         ]
  19.       }
  20.     ]
  21.   }
  22. )
  23. puts response
  1. const response = await client.mget({
  2.   docs: [
  3.     {
  4.       _index: "test",
  5.       _id: "1",
  6.       stored_fields: ["field1", "field2"],
  7.     },
  8.     {
  9.       _index: "test",
  10.       _id: "2",
  11.       stored_fields: ["field3", "field4"],
  12.     },
  13.   ],
  14. });
  15. console.log(response);
  1. GET /_mget
  2. {
  3.   "docs": [
  4.     {
  5.       "_index": "test",
  6.       "_id": "1",
  7.       "stored_fields": [ "field1", "field2" ]
  8.     },
  9.     {
  10.       "_index": "test",
  11.       "_id": "2",
  12.       "stored_fields": [ "field3", "field4" ]
  13.     }
  14.   ]
  15. }

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.

  1. resp = client.mget(
  2.     index="test",
  3.     stored_fields="field1,field2",
  4.     docs=[
  5.         {
  6.             "_id": "1"
  7.         },
  8.         {
  9.             "_id": "2",
  10.             "stored_fields": [
  11.                 "field3",
  12.                 "field4"
  13.             ]
  14.         }
  15.     ],
  16. )
  17. print(resp)
  1. response = client.mget(
  2.   index: 'test',
  3.   stored_fields: 'field1,field2',
  4.   body: {
  5.     docs: [
  6.       {
  7.         _id: '1'
  8.       },
  9.       {
  10.         _id: '2',
  11.         stored_fields: [
  12.           'field3',
  13.           'field4'
  14.         ]
  15.       }
  16.     ]
  17.   }
  18. )
  19. puts response
  1. const response = await client.mget({
  2.   index: "test",
  3.   stored_fields: "field1,field2",
  4.   docs: [
  5.     {
  6.       _id: "1",
  7.     },
  8.     {
  9.       _id: "2",
  10.       stored_fields: ["field3", "field4"],
  11.     },
  12.   ],
  13. });
  14. console.log(response);
  1. GET /test/_mget?stored_fields=field1,field2
  2. {
  3.   "docs": [
  4.     {
  5.       "_id": "1"
  6.     },
  7.     {
  8.       "_id": "2",
  9.       "stored_fields": [ "field3", "field4" ]
  10.     }
  11.   ]
  12. }

Specify document routing

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

  1. resp = client.mget(
  2.     routing="key1",
  3.     docs=[
  4.         {
  5.             "_index": "test",
  6.             "_id": "1",
  7.             "routing": "key2"
  8.         },
  9.         {
  10.             "_index": "test",
  11.             "_id": "2"
  12.         }
  13.     ],
  14. )
  15. print(resp)
  1. response = client.mget(
  2.   routing: 'key1',
  3.   body: {
  4.     docs: [
  5.       {
  6.         _index: 'test',
  7.         _id: '1',
  8.         routing: 'key2'
  9.       },
  10.       {
  11.         _index: 'test',
  12.         _id: '2'
  13.       }
  14.     ]
  15.   }
  16. )
  17. puts response
  1. const response = await client.mget({
  2.   routing: "key1",
  3.   docs: [
  4.     {
  5.       _index: "test",
  6.       _id: "1",
  7.       routing: "key2",
  8.     },
  9.     {
  10.       _index: "test",
  11.       _id: "2",
  12.     },
  13.   ],
  14. });
  15. console.log(response);
  1. GET /_mget?routing=key1
  2. {
  3.   "docs": [
  4.     {
  5.       "_index": "test",
  6.       "_id": "1",
  7.       "routing": "key2"
  8.     },
  9.     {
  10.       "_index": "test",
  11.       "_id": "2"
  12.     }
  13.   ]
  14. }