elasticsearch/elasticsearch — Issue #1583: Update API: Allow to update a document based on a script
Author: kimchy
Created: 2012-01-02 20:01:47+00:00
State: open
Labels: feature, v0.19.0

The update action allows to directly update a specific document based on a script. 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).

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.

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:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
"script" : "ctx._source.tags += tag",
"params" : {
"tag" : "blue"
}
}'

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"
}
}'

Parameters:
-----------

* `routing`: Sets the routing that will be used to route the document to the relevant shard.
* `parent`: Simply sets the routing.
* `timeout`: Timeout waiting for a shard to become available.
* `replication`: The replication type for the delete/index operation (`sync` or `async`).
* `consistency`: The write consistency of the index/delete operation.
* `retry_on_conflict`: How many times to retry if there is a version conflict between getting the document and indexing / deleting it. Defaults to `1`.