Added multi-get document API to REST API

This commit is contained in:
keithhc2 2021-07-29 16:16:15 -07:00
parent 793ce77490
commit 84e9440f18
2 changed files with 142 additions and 1 deletions

View File

@ -3,7 +3,7 @@ layout: default
title: Bulk
parent: Document APIs
grand_parent: REST API reference
nav_order: 20
nav_order: 25
---
# Bulk

View File

@ -0,0 +1,141 @@
---
layout: default
title: Multi-get document
parent: Document APIs
grand_parent: REST API reference
nav_order: 20
---
# Multi-get documents
You can use the multi-get operation to get back multiple documents from one index or multiple indices in one request.
## Example without specifying index in URL
```json
GET _mget
{
"docs": [
{
"_index": "sample-index1",
"_id": "1"
},
{
"_index": "sample-index2",
"_id": "1",
"_source": {
"include": ["Length"]
}
}
]
}
```
## Example of specifying index in URL
```json
GET sample-index1/_mget
{
"docs": [
{
"_type": "_doc",
"_id": "1",
"_source": false
},
{
"_type": "_doc",
"_id": "2",
"_source": [ "Director", "Title" ]
}
]
}
```
## Path and HTTP methods
```
GET _mget
GET <index>/_mget
```
## URL parameters
All multi-get URL parameters are optional.
Parameter | Type | Description
:--- | :--- | :--- | :---
&lt;index&gt; | String | Name of the index to retrieve documents from.
preference | String | The node or shard OpenSearch should perform the operation on. Default is random.
realtime | Boolean | Specifies 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.
refresh | Boolean | If true, OpenSearch refreshes shards to make the operation visible to searching. Default is false.
routing | String | A value used to route the operation to a specific shard.
stored_fields | Boolean | If true, the operation retrieves document fields stored in the index rather than the document's `_source`. Default is false.
_source | String | Whether to include the `_source` field in the query response. Default is true.
_source_excludes | String | A comma-separated list of source fields to exclude in the query response.
_source_includes | String | A 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 indices and the relevant document IDs in the request body. Other fields are optional.
Field | Type | Description | Required
:--- | :--- | :--- | :---
docs | Array | The 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
_id | String | The ID of the document. | Yes if `docs` is specified in the request body
_index | String | Name of the index. | Yes if an index is not specified in the URL
_routing | String | The value of the shard that has the document. | Yes if a routing value was used when indexing the document
_source | Object | Specifies 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.includes | Array | Specifies which fields to include in the query response. For example, `"_source": { "include": ["Title"] }` retrieves `Title` from the index. | No
_source.excludes | Array | Specifies which fields to exclude in the query response. For example, `"_source": { "exclude": ["Director"] }` excludes `Director` from the query response. | No
ids | Array | IDs of the documents to retrieve. Only allowed when an index is specified in the URL. | No
## Response
```json
{
"docs": [
{
"_index": "sample-index1",
"_type": "_doc",
"_id": "1",
"_version": 4,
"_seq_no": 5,
"_primary_term": 19,
"found": true,
"_source": {
"Title": "Batman Begins",
"Director": "Christopher Nolan"
}
},
{
"_index": "sample-index2",
"_type": "_doc",
"_id": "1",
"_version": 1,
"_seq_no": 6,
"_primary_term": 19,
"found": true,
"_source": {
"Title": "The Dark Knight",
"Director": "Christopher Nolan"
}
}
]
}
```
## Response body fields
Field | Description
:--- | :---
_index | The name of the index.
_type | The document's type. OpenSearch only supports one type, which is `_doc`.
_id | The document's ID.
_version | The document's version number. Updated whenever the document changes.
_seq_no | The sequnce number assigned when the document is indexed.
primary_term | The primary term assigned when the document is indexed.
found | Whether the document exists.
_routing | The shard that the document is routed to. If the document is not routed to a particular shard, this field is omitted.
_source | Contains 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.
_fields | Contains the document's data that's stored in the index. Only returned if both `stored_fields` and `found` are true.