From 84e9440f18c893fe4c4b5b0d97d4b4d2bcfcb849 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 29 Jul 2021 16:16:15 -0700 Subject: [PATCH] Added multi-get document API to REST API --- _opensearch/rest-api/document-apis/bulk.md | 2 +- .../rest-api/document-apis/multi-get.md | 141 ++++++++++++++++++ 2 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 _opensearch/rest-api/document-apis/multi-get.md diff --git a/_opensearch/rest-api/document-apis/bulk.md b/_opensearch/rest-api/document-apis/bulk.md index 7ae76357..5ae9da57 100644 --- a/_opensearch/rest-api/document-apis/bulk.md +++ b/_opensearch/rest-api/document-apis/bulk.md @@ -3,7 +3,7 @@ layout: default title: Bulk parent: Document APIs grand_parent: REST API reference -nav_order: 20 +nav_order: 25 --- # Bulk diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md new file mode 100644 index 00000000..6407b54a --- /dev/null +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -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 /_mget +``` + +## URL parameters + +All multi-get URL parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- | :--- +<index> | 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.