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 indexes 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 needs to be enabled
for this feature to work.
For example, let’s index a simple doc:
PUT test/_doc/1 { "counter" : 1, "tags" : ["red"] }
Scripted updates
editNow, we can execute a script that would increment the counter:
POST test/_update/1 { "script" : { "source": "ctx._source.counter += params.count", "lang": "painless", "params" : { "count" : 4 } } }
We can add a tag to the list of tags (if the tag exists, it still gets added, since this is a list):
POST test/_update/1 { "script" : { "source": "ctx._source.tags.add(params.tag)", "lang": "painless", "params" : { "tag" : "blue" } } }
We can remove a tag from the list of tags. Note that the Painless function to
remove
a tag takes as its parameter the array index of the element you wish
to remove, so you need a bit more logic to locate it while avoiding a runtime
error. Note that if the tag was present more than once in the list, this will
remove only one occurrence of it:
POST test/_update/1 { "script" : { "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }", "lang": "painless", "params" : { "tag" : "blue" } } }
In addition to _source
, the following variables are available through
the ctx
map: _index
, _type
, _id
, _version
, _routing
,
and _now
(the current timestamp).
We can also add a new field to the document:
POST test/_update/1 { "script" : "ctx._source.new_field = 'value_of_new_field'" }
Or remove a field from the document:
POST test/_update/1 { "script" : "ctx._source.remove('new_field')" }
And, we can even change the operation that is executed. This example deletes
the doc if the tags
field contains green
, otherwise it does nothing
(noop
):
POST test/_update/1 { "script" : { "source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'none' }", "lang": "painless", "params" : { "tag" : "green" } } }
Updates with a partial document
editThe update API also supports 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).
To fully replace the existing document, the index
API should
be used instead.
The following partial update adds a new field to the
existing document:
POST test/_update/1 { "doc" : { "name" : "new_name" } }
If both doc
and script
are specified, then doc
is ignored. Best is
to put your field pairs of the partial document in the script itself.
Detecting noop updates
editIf doc
is specified its value is merged with the existing _source
.
By default updates that don’t change anything detect that they don’t change anything and return "result": "noop"
like this:
POST test/_update/1 { "doc" : { "name" : "new_name" } }
If name
was new_name
before the request was sent then the entire update
request is ignored. The result
element in the response returns noop
if
the request was ignored.
{ "_shards": { "total": 0, "successful": 0, "failed": 0 }, "_index": "test", "_type": "_doc", "_id": "1", "_version": 7, "result": "noop" }
You can disable this behavior by setting "detect_noop": false
like this:
POST test/_update/1 { "doc" : { "name" : "new_name" }, "detect_noop": false }
Upserts
editIf the document does not already exist, the contents of the upsert
element
will be inserted as a new document. If the document does exist, then the
script
will be executed instead:
POST test/_update/1 { "script" : { "source": "ctx._source.counter += params.count", "lang": "painless", "params" : { "count" : 4 } }, "upsert" : { "counter" : 1 } }
scripted_upsert
editIf you would like your script to run regardless of whether the document exists
or not — i.e. the script handles initializing the document instead of the
upsert
element — then set scripted_upsert
to true
:
POST sessions/_update/dh3sgudg8gsrgl { "scripted_upsert":true, "script" : { "id": "my_web_session_summariser", "params" : { "pageViewEvent" : { "url":"foo.com/bar", "response":404, "time":"2014-01-01 12:32" } } }, "upsert" : {} }
doc_as_upsert
editInstead of sending a partial doc
plus an upsert
doc, setting
doc_as_upsert
to true
will use the contents of doc
as the upsert
value:
POST test/_update/1 { "doc" : { "name" : "new_name" }, "doc_as_upsert" : true }
Parameters
editThe update operation supports the following query-string parameters:
|
In between the get and indexing phases of the update, it is possible that
another process might have already updated the same document. By default, the
update will fail with a version conflict exception. The |
|
Routing is used to route the update request to the right shard and sets the routing for the upsert request if the document being updated doesn’t exist. Can’t be used to update the routing of an existing document. |
|
Timeout waiting for a shard to become available. |
|
The number of shard copies required to be active before proceeding with the update operation. See here for details. |
|
Control when the changes made by this request are visible to search. See refresh. |
|
Allows to control if and how the updated source should be returned in the response. By default the updated source is not returned. See Source filtering for details. |
|
The update API uses the Elasticsearch versioning support internally to make
sure the document doesn’t change during the update. You can use the |
The update API does not support versioning other than internal
External (version types external
and external_gte
) or forced (version type force
)
versioning is not supported by the update API as it would result in Elasticsearch
version numbers being out of sync with the external system. Use the
index
API instead.
-
if_seq_no
andif_primary_term
-
Update operations can be made conditional and only be performed if the last
modification to the document was assigned the sequence number and primary
term specified by the
if_seq_no
andif_primary_term
parameters. If a mismatch is detected, the operation will result in aVersionConflictException
and a status code of 409. See Optimistic concurrency control for more details.