From 793ce77490ae27f0b9a1d2a9db99206f7fb94b99 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 22 Jul 2021 14:24:17 -0700 Subject: [PATCH] Added update document to REST API reference --- .../rest-api/document-apis/delete-document.md | 3 +- .../rest-api/document-apis/get-documents.md | 1 + .../rest-api/document-apis/update-document.md | 124 ++++++++++++++++++ 3 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 _opensearch/rest-api/document-apis/update-document.md diff --git a/_opensearch/rest-api/document-apis/delete-document.md b/_opensearch/rest-api/document-apis/delete-document.md index 7f167ac4..0d56a3ec 100644 --- a/_opensearch/rest-api/document-apis/delete-document.md +++ b/_opensearch/rest-api/document-apis/delete-document.md @@ -2,7 +2,8 @@ layout: default title: Delete document parent: Document APIs -nav_order: 10 +grand_parent: REST API reference +nav_order: 15 --- # Get document diff --git a/_opensearch/rest-api/document-apis/get-documents.md b/_opensearch/rest-api/document-apis/get-documents.md index a7231b39..931e89a1 100644 --- a/_opensearch/rest-api/document-apis/get-documents.md +++ b/_opensearch/rest-api/document-apis/get-documents.md @@ -2,6 +2,7 @@ layout: default title: Get document parent: Document APIs +grand_parent: REST API reference nav_order: 5 --- diff --git a/_opensearch/rest-api/document-apis/update-document.md b/_opensearch/rest-api/document-apis/update-document.md new file mode 100644 index 00000000..23b06773 --- /dev/null +++ b/_opensearch/rest-api/document-apis/update-document.md @@ -0,0 +1,124 @@ +--- +layout: default +title: Update document +parent: Document APIs +grand_parent: REST API reference +nav_order: 10 +--- + +# Update document + +If you need to update a document's fields in your index, you can use the update document API operation. You can do so by specifying the new data you want in your index or by including a script in your request body, which OpenSearch runs to update the document. + +## Example + +```json +POST /sample-index1/_update/1 +{ + "doc": { + "first_name" : "Bruce", + "last_name" : "Wayne" + } +} +``` + +## Script example + +```json +POST /test-index1/_update/1 +{ + "script" : { + "source": "ctx._source.oldValue += params.newValue", + "lang": "painless", + "params" : { + "newValue" : 10 + } + } +} +``` + +## Path and HTTP methods + +``` +POST //_update/<_id> +``` + +## URL parameters + +Parameter | Type | Description | Required +:--- | :--- | :--- | :--- +<index-name> | String | Name of the index. | Yes +<_id> | String | The ID of the document to update. | Yes +if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No +if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No +lang | String | Language of the script. Default is `painless`. | No +require_alias | Boolean | Specifies whether the destination must be an index alias. Default is false. | No +refresh | Enum | If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is false. | No +retry_on_conflict | Integer | The amount of times OpenSearch should retry the operation if there's a document conflict. Default is 0. | No +routing | String | Value used to route the operation to a specific shard. | No +_source | List | Whether to include the `_source` field in the response body. Default is true. | No +_source_excludes | List | A comma-separated list of source fields to exclude in the query response. | No +_source_includes | List | A comma-separated list of source fields to include in the query response. | No +timeout | Time | How long to wait for a response from the cluster. | No +wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the update request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed. | No + +## Request body + +Your request body must contain the information you want to update your document with. If you just want to replace certain fields in your document, your request body must include a `doc` object, which has the fields you want to update. + +```json +{ + "doc": { + "first_name": "Thomas", + "last_name": "Wayne" + } +} +``` + +You can also use a script to tell OpenSearch how to update your document. + +```json +{ + "script" : { + "source": "ctx._source.oldValue += params.newValue", + "lang": "painless", + "params" : { + "newValue" : 10 + } + } +} +``` + +## Response +```json +{ + "_index": "sample-index1", + "_type": "_doc", + "_id": "1", + "_version": 3, + "result": "updated", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 4, + "_primary_term": 17 +} +``` + +## 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. +_result | The result of the delete operation. +_shards | Detailed information about the cluster's shards. +total | The total number of shards. +successful | The number of shards OpenSearch succssfully deleted the document from. +failed | The number of shards OpenSearch failed to delete the document from. +_seq_no | The sequence number assigned when the document was indexed. +_primary_term | The primary term assigned when the document was indexed.