Merge pull request #73 from opensearch-project/document-apis

Added get document API and some reorganization
This commit is contained in:
Andrew Etter 2021-07-08 12:16:41 -07:00 committed by GitHub
commit 62491a2a98
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 109 additions and 3 deletions

View File

@ -1,8 +1,9 @@
---
layout: default
title: Bulk
parent: REST API reference
nav_order: 5
parent: Document APIs
grand_parent: REST API reference
nav_order: 20
---
# Bulk
@ -32,7 +33,7 @@ POST _bulk
POST {index}/_bulk
```
Specifying the index in the path means you don't need to include it in the [request body](#request-body).
Specifying the index in the path means you don't need to include it in the [request body]({{site.url}}{{site.baseurl}}/opensearch/rest-api/document-apis/bulk/#request-body).
OpenSearch also accepts PUT requests to the `_bulk` path, but we highly recommend using POST. The accepted usage of PUT---adding or replacing a single resource at a given path---doesn't make sense for bulk requests.
{: .note }

View File

@ -0,0 +1,77 @@
---
layout: default
title: Get document
parent: Document APIs
grand_parent: REST API reference
nav_order: 5
---
# Get document
After adding a JSON document to your index, you can use the get document API operation to retrieve the document's information and data.
## Example
```json
GET sample-index1/_doc/1
```
## Path and HTTP methods
```
GET <index>/_doc/<_id>
HEAD <index>/_doc/<_id>
```
```
GET <index>/_source/<_id>
HEAD <index>/_source/<_id>
```
## URL parameters
All get document URL parameters are optional.
Parameter | Type | Description
:--- | :--- | :---
preference | string | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes get document operations on random shards.
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 response body. 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.
version | integer | The version of the document to return, which must match the current version of the document.
version_type | enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current verison). For example, to retrieve version 3 of a document, use `/_doc/1?version=3&version_type=external`.
## Response
```json
{
"_index": "sample-index1",
"_type": "_doc",
"_id": "1",
"_version": 1,
"_seq_no": 0,
"_primary_term": 9,
"found": true,
"_source": {
"text": "This is just some sample text."
}
}
```
## 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.

View File

@ -0,0 +1,28 @@
---
layout: default
title: Document APIs
parent: REST API reference
has_children: true
nav_order: 7
---
# Document APIs
The document APIs allow you to handle documents relative to your index, such as adding, updating, and deleting documents.
Document APIs are separated into two categories: single document operations and multi-document operations. Multi-document operations offer performance advantages over submitting many individual requests, so whenever practical, we recommend that you use multi-document operations.
## Single document operations
- Index
- Get
- Delete
- Update
## Multi-document operations
- Bulk
- Multi get
- Delete by query
- Update by query
- Reindex