Update document

Introduced 1.0

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

  1. POST /sample-index1/_update/1
  2. {
  3. "doc": {
  4. "first_name" : "Bruce",
  5. "last_name" : "Wayne"
  6. }
  7. }

Script example

  1. POST /test-index1/_update/1
  2. {
  3. "script" : {
  4. "source": "ctx._source.secret_identity = \"Batman\""
  5. }
  6. }

Path and HTTP methods

  1. POST /<index>/_update/<_id>

URL parameters

ParameterTypeDescriptionRequired
<index>StringName of the index.Yes
<_id>StringThe ID of the document to update.Yes
if_seq_noIntegerOnly perform the delete operation if the document’s version number matches the specified number.No
if_primary_termIntegerPerform the update operation if the document has the specified primary term.No
langStringLanguage of the script. Default is painless.No
require_aliasBooleanSpecifies whether the destination must be an index alias. Default is false.No
refreshEnumIf 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_conflictIntegerThe amount of times OpenSearch should retry the operation if there’s a document conflict. Default is 0.No
routingStringValue to route the update operation to a specific shard.No
_sourceListWhether to include the _source field in the response body. Default is true.No
_source_excludesListA comma-separated list of source fields to exclude in the query response.No
_source_includesListA comma-separated list of source fields to include in the query response.No
timeoutTimeHow long to wait for a response from the cluster.No
wait_for_active_shardsStringThe 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.

  1. {
  2. "doc": {
  3. "first_name": "Thomas",
  4. "last_name": "Wayne"
  5. }
  6. }

You can also use a script to tell OpenSearch how to update your document.

  1. {
  2. "script" : {
  3. "source": "ctx._source.oldValue += params.newValue",
  4. "lang": "painless",
  5. "params" : {
  6. "newValue" : 10
  7. }
  8. }
  9. }

Response

  1. {
  2. "_index": "sample-index1",
  3. "_type": "_doc",
  4. "_id": "1",
  5. "_version": 3,
  6. "result": "updated",
  7. "_shards": {
  8. "total": 2,
  9. "successful": 2,
  10. "failed": 0
  11. },
  12. "_seq_no": 4,
  13. "_primary_term": 17
  14. }

Response body fields

FieldDescription
_indexThe name of the index.
_typeThe document’s type. OpenSearch only supports one type, which is _doc.
_idThe document’s ID.
_versionThe document’s version.
_resultThe result of the delete operation.
_shardsDetailed information about the cluster’s shards.
totalThe total number of shards.
successfulThe number of shards OpenSearch succssfully deleted the document from.
failedThe number of shards OpenSearch failed to delete the document from.
_seq_noThe sequence number assigned when the document was indexed.
_primary_termThe primary term assigned when the document was indexed.