Multi-get documents

Introduced 1.0

The multi-get operation allows you to run multiple GET operations in one request, so you can get back all documents that match your criteria.

Example without specifying index in URL

  1. GET _mget
  2. {
  3. "docs": [
  4. {
  5. "_index": "sample-index1",
  6. "_id": "1"
  7. },
  8. {
  9. "_index": "sample-index2",
  10. "_id": "1",
  11. "_source": {
  12. "include": ["Length"]
  13. }
  14. }
  15. ]
  16. }

copy

Example of specifying index in URL

  1. GET sample-index1/_mget
  2. {
  3. "docs": [
  4. {
  5. "_id": "1",
  6. "_source": false
  7. },
  8. {
  9. "_id": "2",
  10. "_source": [ "Director", "Title" ]
  11. }
  12. ]
  13. }

copy

Path and HTTP methods

  1. GET _mget
  2. GET <index>/_mget

URL parameters

All multi-get URL parameters are optional.

ParameterTypeDescription
<index>StringName of the index to retrieve documents from.
preferenceStringSpecifies the nodes or shards OpenSearch should execute the multi-get operation on. Default is random.
realtimeBooleanSpecifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is true.
refreshBooleanIf true, OpenSearch refreshes shards to make the multi-get operation available to search results. Valid options are true, false, and wait_for, which tells OpenSearch to wait for a refresh before executing the operation. Default is false.
routingStringValue used to route the multi-get operation to a specific shard.
stored_fieldsBooleanSpecifies whether OpenSearch should retrieve documents fields from the index instead of the document’s _source. Default is false.
_sourceStringWhether to include the _source field in the query response. Default is true.
_source_excludesStringA comma-separated list of source fields to exclude in the query response.
_source_includesStringA comma-separated list of source fields to include in the query response.

Request body

If you don’t specify an index in your request’s URL, you must specify your target indexes and the relevant document IDs in the request body. Other fields are optional.

FieldTypeDescriptionRequired
docsArrayThe documents you want to retrieve data from. Can contain the attributes: _id, _index, _routing, _source, and _stored_fields. If you specify an index in the URL, you can omit this field and add IDs of the documents to retrieve.Yes if an index is not specified in the URL
_idStringThe ID of the document.Yes if docs is specified in the request body
_indexStringName of the index.Yes if an index is not specified in the URL
_routingStringThe value of the shard that has the document.Yes if a routing value was used when indexing the document
_sourceObjectSpecifies whether to return the _source field from an index (boolean), whether to return specific fields (array), or whether to include or exclude certain fields.No
_source.includesArraySpecifies which fields to include in the query response. For example, “_source”: { “include”: [“Title”] } retrieves Title from the index.No
_source.excludesArraySpecifies which fields to exclude in the query response. For example, “_source”: { “exclude”: [“Director”] } excludes Director from the query response.No
idsArrayIDs of the documents to retrieve. Only allowed when an index is specified in the URL.No

Response

  1. {
  2. "docs": [
  3. {
  4. "_index": "sample-index1",
  5. "_id": "1",
  6. "_version": 4,
  7. "_seq_no": 5,
  8. "_primary_term": 19,
  9. "found": true,
  10. "_source": {
  11. "Title": "Batman Begins",
  12. "Director": "Christopher Nolan"
  13. }
  14. },
  15. {
  16. "_index": "sample-index2",
  17. "_id": "1",
  18. "_version": 1,
  19. "_seq_no": 6,
  20. "_primary_term": 19,
  21. "found": true,
  22. "_source": {
  23. "Title": "The Dark Knight",
  24. "Director": "Christopher Nolan"
  25. }
  26. }
  27. ]
  28. }

Response body fields

FieldDescription
_indexThe name of the index.
_idThe document’s ID.
_versionThe document’s version number. Updated whenever the document changes.
_seq_noThe sequence number assigned when the document is indexed.
primary_termThe primary term assigned when the document is indexed.
foundWhether the document exists.
_routingThe shard that the document is routed to. If the document is not routed to a particular shard, this field is omitted.
_sourceContains the document’s data if found is true. If _source is set to false or stored_fields is set to true in the URL parameters, this field is omitted.
_fieldsContains the document’s data that’s stored in the index. Only returned if both stored_fields and found are true.