Update API

The 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.

By default if doc is specified then the document is always updated even if the merging process doesn’t cause any changes. Specifying detect_noop as true will cause Elasticsearch to check if there are changes and, if there aren’t, turn the update request into a noop. For example:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "doc" : {
        "name" : "new_name"
    },
    "detect_noop": true
}'

If name was new_name before the request was sent then the entire update request is ignored.

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

If the document does not exist you may want your update script to run anyway in order to initialize the document contents using business logic unknown to the client. In this case pass the new scripted_upsert parameter with the value true.

curl -XPOST 'localhost:9200/sessions/session/dh3sgudg8gsrgl/_update' -d '{
    "script_id" : "my_web_session_summariser",
    "scripted_upsert":true,
    "params" : {
        "pageViewEvent" : {
        	"url":"foo.com/bar",
        	"response":404,
        	"time":"2014-01-01 12:32"
        }
    },
    "upsert" : {
    }
}'

The default scripted_upsert setting is false meaning the script is not executed for inserts. However, in scenarios like the one above we may be using a non-trivial script stored using the new "indexed scripts" feature. The script may be deriving properties like the duration of our web session based on observing multiple page view events so the client can supply a blank "upsert" document and allow the script to fill in most of the details using the events passed in the params element.

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

The update operation supports similar parameters as the index API, including:

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.

In addition to _source, the following variables are available through the ctx map: _index, _type, _id, _version, _routing, _parent, _timestamp, _ttl.