WARNING: Version 1.3 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Update API
editUpdate API
editThe update API allows to update a document based on a script provided. The operation gets the document (collocated with the shard) from the index, runs the script (with optional script language and parameters), and index back the result (also allows to delete, or ignore the operation). It uses versioning to make sure no updates have happened during the "get" and "reindex".
Note, this operation still means full reindex of the document, it just
removes some network roundtrips and reduces chances of version conflicts
between the get and the index. The _source
field need to be enabled
for this feature to work.
For example, lets index a simple doc:
curl -XPUT localhost:9200/test/type1/1 -d '{ "counter" : 1, "tags" : ["red"] }'
Now, we can execute a script that would increment the counter:
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "script" : "ctx._source.counter += count", "params" : { "count" : 4 } }'
We can also add a tag to the list of tags (note, if the tag exists, it will still add it, since its a list):
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "script" : "ctx._source.tags += tag", "params" : { "tag" : "blue" } }'
We can also add a new field to the document:
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "script" : "ctx._source.name_of_new_field = \"value_of_new_field\"" }'
We can also remove a field from the document:
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "script" : "ctx._source.remove(\"name_of_field\")" }'
And, we can delete the doc if the tags contain blue, or ignore (noop):
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "script" : "ctx._source.tags.contains(tag) ? ctx.op = \"delete\" : ctx.op = \"none\"", "params" : { "tag" : "blue" } }'
Note: Be aware of MVEL and handling of ternary operators and assignments. Assignment operations have lower precedence than the ternary operator. Compare the following statements:
// Will NOT update the tags array ctx._source.tags.contains(tag) ? ctx.op = \"none\" : ctx._source.tags += tag // Will update ctx._source.tags.contains(tag) ? (ctx.op = \"none\") : ctx._source.tags += tag // Also works if (ctx._source.tags.contains(tag)) { ctx.op = \"none\" } else { ctx._source.tags += tag }
The update API also support passing a partial document, which will be merged into the existing document (simple recursive merge, inner merging of objects, replacing core "keys/values" and arrays). For example:
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "doc" : { "name" : "new_name" } }'
If both doc
and script
is specified, then doc
is ignored. Best is
to put your field pairs of the partial document in the script itself.
Upserts
editThere is also support for upsert
. If the document does
not already exists, the content of the upsert
element will be used to
index the fresh doc:
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "script" : "ctx._source.counter += count", "params" : { "count" : 4 }, "upsert" : { "counter" : 1 } }'
Last, the upsert facility also supports doc_as_upsert
. So that the
provided document will be inserted if the document does not already
exist. This will reduce the amount of data that needs to be sent to
elasticsearch.
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{ "doc" : { "name" : "new_name" }, "doc_as_upsert" : true }'
Parameters
editThe update operation supports similar parameters as the index API, including:
|
Sets the routing that will be used to route the document to the relevant shard. |
|
Simply sets the routing. |
|
Timeout waiting for a shard to become available. |
|
The replication type for the delete/index operation (sync or async). |
|
The write consistency of the index/delete operation. |
|
Refresh the relevant primary and replica shards (not the whole index) immediately after the operation occurs, so that the updated document appears in search results immediately. |
|
return the relevant fields from the updated document.
Support |
|
the Update API uses the Elasticsearch’s versioning
support internally to make sure the document doesn’t change
during the update. You can use the |
And also support retry_on_conflict
which controls how many times to
retry if there is a version conflict between getting the document and
indexing / deleting it. Defaults to 0
.
It also allows to update the ttl
of a document using ctx._ttl
and
timestamp using ctx._timestamp
. Note that if the timestamp is not
updated and not extracted from the _source
it will be set to the
update date.