You're viewing version 2.16 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

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 to be in your index or by including a script in your request body, which OpenSearch runs to update the document. By default, the update operation only updates a document that exists in the index. If a document does not exist, the API returns an error. To upsert a document (update the document that exists or index a new one), use the upsert operation.

Example

POST /sample-index1/_update/1
{
  "doc": {
    "first_name" : "Bruce",
    "last_name" : "Wayne"
  }
}

Script example

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

Path and HTTP methods

POST /<index>/_update/<_id>

URL parameters

Request body

Your request body must contain the information with which you want to update your document. If you only want to replace certain fields in your document, your request body must include a doc object containing the fields that you want to update:

{
  "doc": {
    "first_name": "Thomas",
    "last_name": "Wayne"
    }
}

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

{
  "script" : {
    "source": "ctx._source.oldValue += params.newValue",
    "lang": "painless",
    "params" : {
      "newValue" : 10
    }
  }
}

Upsert

Upsert is an operation that conditionally either updates an existing document or inserts a new one based on information in the object.

In the following example, the upsert operation updates the first_name and last_name fields if a document already exists. If a document does not exist, a new one is indexed using content in the upsert object.

POST /sample-index1/_update/1
{
  "doc": {
    "first_name": "Martha",
    "last_name": "Rivera"
  },
  "upsert": {
    "last_name": "Oliveira",
    "age": "31"
  }
}

Consider an index that contains the following document:

{
  "_index": "sample-index1",
  "_id": "1",
  "_score": 1,
  "_source": {
    "first_name": "Bruce",
    "last_name": "Wayne"
  }
}

After the upsert operation, the document’s first_name and last_name fields are updated:

{
  "_index": "sample-index1",
  "_id": "1",
  "_score": 1,
  "_source": {
    "first_name": "Martha",
    "last_name": "Rivera"
  }
}

If the document does not exist in the index, a new document is indexed with the fields specified in the upsert object:

{
  "_index": "sample-index1",
  "_id": "1",
  "_score": 1,
  "_source": {
    "last_name": "Oliveira",
    "age": "31"
  }
}

You can also add doc_as_upsert to the request and set it to true to use the information in the doc field for performing the upsert operation:

POST /sample-index1/_update/1
{
  "doc": {
    "first_name": "Martha",
    "last_name": "Oliveira",
    "age": "31"
  },
  "doc_as_upsert": true
}

Consider an index that contains the following document:

{
  "_index": "sample-index1",
  "_id": "1",
  "_score": 1,
  "_source": {
    "first_name": "Bruce",
    "last_name": "Wayne"
  }
}

After the upsert operation, the document’s first_name and last_name fields are updated and an age field is added. If the document does not exist in the index, a new document is indexed with the fields specified in the upsert object. In both cases, the document is as follows:

{
  "_index": "sample-index1",
  "_id": "1",
  "_score": 1,
  "_source": {
    "first_name": "Martha",
    "last_name": "Oliveira",
    "age": "31"
  }
}

Example response

{
  "_index": "sample-index1",
  "_id": "1",
  "_version": 3,
  "result": "updated",
  "_shards": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "_seq_no": 4,
  "_primary_term": 17
}

Response body fields