Merge pull request #121 from opensearch-project/document-rest-apis

Added multi-get document API to REST API

_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

_opensearch/rest-api/document-apis/multi-get.md

@@ -0,0 +1,143 @@
+---
+layout: default
+title: Multi-get document
+parent: Document APIs
+grand_parent: REST API reference
+nav_order: 20
+---
+
+# Multi-get documents
+
+Introduced 1.0 {: .label .label-purple }
+
+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
+
+```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 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.
+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.