269 lines
8.1 KiB
Plaintext
269 lines
8.1 KiB
Plaintext
[[docs-update]]
|
|
== 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 needs to be enabled
|
|
for this feature to work.
|
|
|
|
For example, lets index a simple doc:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPUT localhost:9200/test/type1/1 -d '{
|
|
"counter" : 1,
|
|
"tags" : ["red"]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
=== Scripted updates
|
|
|
|
Now, we can execute a script that would increment the counter:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"script" : {
|
|
"inline": "ctx._source.counter += params.count",
|
|
"lang": "painless",
|
|
"params" : {
|
|
"count" : 4
|
|
}
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
We can add a tag to the list of tags (note, if the tag exists, it
|
|
will still add it, since its a list):
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"script" : {
|
|
"inline": "ctx._source.tags += 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`,
|
|
`_parent`.
|
|
|
|
We can also add a new field to the document:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"script" : "ctx._source.name_of_new_field = \"value_of_new_field\""
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
Or remove a field from the document:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"script" : "ctx._source.remove(\"name_of_field\")"
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
And, we can even change the operation that is executed. This example deletes
|
|
the doc if the `tags` field contain `blue`, otherwise it does nothing
|
|
(`noop`):
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"script" : {
|
|
"inline": "ctx._source.tags.contains(params.tag) ? ctx.op = \"delete\" : ctx.op = \"none\"",
|
|
"lang": "painless",
|
|
"params" : {
|
|
"tag" : "blue"
|
|
}
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
=== Updates with a partial document
|
|
|
|
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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"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.
|
|
|
|
[float]
|
|
=== Detecting noop updates
|
|
If `doc` is specified its value is merged with the existing `_source`. By
|
|
default the document is only reindexed if the new `_source` field differs from
|
|
the old. Setting `detect_noop` to `false` will cause Elasticsearch to always
|
|
update the document even if it hasn't changed. For example:
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"doc" : {
|
|
"name" : "new_name"
|
|
},
|
|
"detect_noop": false
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
If `name` was `new_name` before the request was sent then document is still
|
|
reindexed.
|
|
|
|
[[upserts]]
|
|
[float]
|
|
=== Upserts
|
|
|
|
If 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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"script" : {
|
|
"inline": "ctx._source.counter += params.count",
|
|
"lang": "painless",
|
|
"params" : {
|
|
"count" : 4
|
|
}
|
|
},
|
|
"upsert" : {
|
|
"counter" : 1
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
==== `scripted_upsert`
|
|
|
|
If 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`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/sessions/session/dh3sgudg8gsrgl/_update' -d '{
|
|
"scripted_upsert":true,
|
|
"script" : {
|
|
"id": "my_web_session_summariser",
|
|
"params" : {
|
|
"pageViewEvent" : {
|
|
"url":"foo.com/bar",
|
|
"response":404,
|
|
"time":"2014-01-01 12:32"
|
|
}
|
|
}
|
|
},
|
|
"upsert" : {}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
==== `doc_as_upsert`
|
|
|
|
Instead 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:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
|
|
"doc" : {
|
|
"name" : "new_name"
|
|
},
|
|
"doc_as_upsert" : true
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
|
|
[float]
|
|
=== Parameters
|
|
|
|
The update operation supports the following query-string parameters:
|
|
|
|
[horizontal]
|
|
`retry_on_conflict`::
|
|
|
|
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 `retry_on_conflict`
|
|
parameter controls how many times to retry the update before finally throwing
|
|
an exception.
|
|
|
|
`routing`::
|
|
|
|
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.
|
|
|
|
`parent`::
|
|
|
|
Parent is used to route the update request to the right shard and sets the
|
|
parent for the upsert request if the document being updated doesn't exist.
|
|
Can't be used to update the `parent` of an existing document.
|
|
If an alias index routing is specified then it overrides the parent routing and it is used to route the request.
|
|
|
|
`timeout`::
|
|
|
|
Timeout waiting for a shard to become available.
|
|
|
|
`consistency`::
|
|
|
|
The write consistency of the index/delete operation.
|
|
|
|
`refresh`::
|
|
|
|
Control when the changes made by this request are visible to search. See
|
|
<<docs-refresh>>.
|
|
|
|
`fields`::
|
|
|
|
Return the relevant fields from the updated document. Specify `_source` to
|
|
return the full updated source.
|
|
|
|
`version` & `version_type`::
|
|
|
|
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 `version`
|
|
parameter to specify that the document should only be updated if its version
|
|
matches the one specified. By setting version type to `force` you can force
|
|
the new version of the document after update (use with care! with `force`
|
|
there is no guarantee the document didn't change).
|
|
|
|
[NOTE]
|
|
.The update API does not support external versioning
|
|
=====================================================
|
|
|
|
External versioning (version types `external` & `external_gte`) 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
|
|
<<docs-index_,`index` API>> instead.
|
|
|
|
=====================================================
|