From 84e9440f18c893fe4c4b5b0d97d4b4d2bcfcb849 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 29 Jul 2021 16:16:15 -0700 Subject: [PATCH 1/4] 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 7ae76357ff..5ae9da57c4 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 0000000000..6407b54ae0 --- /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. From f315193267a71611dfd2b36cc00e9c555d6142ef Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 30 Jul 2021 14:31:42 -0700 Subject: [PATCH 2/4] Added versioning label --- _opensearch/rest-api/document-apis/multi-get.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 6407b54ae0..0290245a60 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -8,6 +8,8 @@ nav_order: 20 # Multi-get documents +Introduced 1.0 {: .label .label-purple } + 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 From 59f7ffeb99200c7b688ba7b2373c17f45cd4b447 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 4 Aug 2021 12:00:36 -0700 Subject: [PATCH 3/4] Addressed comments --- _opensearch/rest-api/document-apis/multi-get.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 0290245a60..2951cace57 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -10,7 +10,7 @@ nav_order: 20 Introduced 1.0 {: .label .label-purple } -You can use the multi-get operation to get back multiple documents from one index or multiple indices in one request. +The multi-get operation allows you to execute multiple GET operations in one request, so you can get back all documents that match your criteria. ## Example without specifying index in URL @@ -69,7 +69,7 @@ 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. +preference | String | The node or shard that 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. From a3808e858a63673a831dab9f05cd3715d0bf1415 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 4 Aug 2021 12:03:41 -0700 Subject: [PATCH 4/4] Minor style changes --- _opensearch/rest-api/document-apis/multi-get.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_opensearch/rest-api/document-apis/multi-get.md b/_opensearch/rest-api/document-apis/multi-get.md index 2951cace57..844faf29f5 100644 --- a/_opensearch/rest-api/document-apis/multi-get.md +++ b/_opensearch/rest-api/document-apis/multi-get.md @@ -70,11 +70,11 @@ Parameter | Type | Description :--- | :--- | :--- | :--- <index> | String | Name of the index to retrieve documents from. preference | String | The node or shard that 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. +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. +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.