Update a document

POST /{index}/_update/{id}

Auth

Update a document by running a script or passing a partial document.

If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.

The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:

Gets the document (collocated with the shard) from the index.
Runs the specified script.
Indexes the result.

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.

The _source field must be enabled to use this API. In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp). For usage examples such as partial updates, upserts, and scripted updates, see the External documentation.

Required privileges

Index privileges write

Path parameters

index string required: The name of the target index. By default, the index is created automatically if it doesn't exist.
id string required: A unique identifier for the document to be updated.

Query parameters

if_primary_term number: Only perform the operation if the document has this primary term.
if_seq_no number: Only perform the operation if the document has this sequence number.
include_source_on_error boolean · default: true: True or false if to include the document source in the error message in case of parsing errors.
lang string · default: painless: The script language.
refresh enum · default: false: If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes.; Values: true false wait_for
require_alias boolean · default: false: If true, the destination must be an index alias.
retry_on_conflict number · default: 0: The number of times the operation should be retried when a conflict occurs.
timeout union oneOf · default: 1m: The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.; Values: -1 0
_source union oneOf · default: true: If false, source retrieval is turned off. You can also specify a comma-separated list of the fields you want to retrieve.; One of: boolean or string
_source_excludes union string | string[]: The source fields you want to exclude.
_source_includes union string | string[]: The source fields you want to retrieve.

Request body

detect_noop boolean · default: true: If true, the result in the response is set to noop (no operation) when there are no changes to the document.
doc object: A partial update to an existing document. If both doc and script are specified, doc is ignored.
doc_as_upsert boolean · default: false: If true, use the contents of 'doc' as the value of 'upsert'. NOTE: Using ingest pipelines with doc_as_upsert is not supported.
script string: The script to run to update the document.
scripted_upsert boolean · default: false: If true, run the script whether or not the document exists.
_source union oneOf · default: true: If false, turn off source retrieval. You can also specify a comma-separated list of the fields you want to retrieve.; One of:
upsert object: If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run.

Response

application/json

_id string required: The unique identifier for the added document.
_index string required: The name of the index the document was added to.
_primary_term number: The primary term assigned to the document for the indexing operation.
result enum required: The result of the indexing operation: created or updated.; Values: created updated deleted not_found noop
_seq_no number: The sequence number assigned to the document for the indexing operation. Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.
_shards object required: Information about the replication process of the operation.
_version number required: The document version, which is incremented each time the document is updated.
failure_store enum: The role of the failure store in this document response; Values: not_applicable_or_unknown used not_enabled failed
forced_refresh boolean
get object