Added multi-get document API to REST API
This commit is contained in:
parent
793ce77490
commit
84e9440f18
|
@ -3,7 +3,7 @@ layout: default
|
|||
title: Bulk
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 20
|
||||
nav_order: 25
|
||||
---
|
||||
|
||||
# Bulk
|
||||
|
|
|
@ -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
|
||||
:--- | :--- | :--- | :---
|
||||
<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.
|
Loading…
Reference in New Issue