diff --git a/docs/reference/docs/index_.asciidoc b/docs/reference/docs/index_.asciidoc index 462755adfe1..465c62371cd 100644 --- a/docs/reference/docs/index_.asciidoc +++ b/docs/reference/docs/index_.asciidoc @@ -34,7 +34,7 @@ using a PUT request. Omit to automatically generate an ID when using a POST request. -[[docs--api-query-params]] +[[docs-index-api-query-params]] ==== {api-query-parms-title} include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no] diff --git a/docs/reference/docs/update.asciidoc b/docs/reference/docs/update.asciidoc index c0cc88bb4f5..1a732cf1246 100644 --- a/docs/reference/docs/update.asciidoc +++ b/docs/reference/docs/update.asciidoc @@ -1,18 +1,86 @@ [[docs-update]] === Update API +++++ +Update +++++ -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 indexes back the result (also allows to delete, or ignore the -operation). +Updates a document using the specified script. -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. +[[docs-update-api-request]] +==== {api-request-title} -For example, let's index a simple doc: +`POST /` + +[[update-api-desc]] +==== {api-description-title} + +Enables you script document updates. The script can update, delete, or skip +modifying the document. The update API also supports passing a partial document, +which is merged into the existing document. To fully replace an existing +document, use the <>. + +This operation: + +. Gets the document (collocated with the shard) from the index. +. Runs the specified script. +. Indexes the result. + +The document must still be reindexed, but using `update` removes some network +roundtrips and reduces chances of version conflicts between the GET and the +index operation. + +The `_source` field must be enabled to use `update`. In addition to `_source`, +you can access the following variables through the `ctx` map: `_index`, +`_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp). + +[[docs-update-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) Name of the target index. By default, the index is created +automatically if it doesn't exist. For more information, see <>. + +`<_id>`:: +(Required, string) Unique identifier for the document to be updated. + +[[docs-update-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term] + +`lang`:: +(Optional, string) The script language. Default: `painless`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh] + +`retry_on_conflict`:: +(Optional, integer) Specify how many times should the operation be retried when + a conflict occurs. Default: 0. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing] + +`_source`:: +(Optional, list) Set to `false` to disable source retrieval (default: `true`). +You can also specify a comma-separated list of the fields you want to retrieve. + +`_source_excludes`:: +(Optional, list) Specify the source fields you want to exclude. + +`_source_includes`:: +(Optional, list) Specify the source fields you want to retrieve. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards] + +[[update-api-example]] +==== {api-examples-title} + +First, let's index a simple doc: [source,js] -------------------------------------------------- @@ -24,10 +92,8 @@ PUT test/_doc/1 -------------------------------------------------- // CONSOLE -[float] -==== Scripted updates - -Now, we can execute a script that would increment the counter: +To increment the counter, you can submit an update request with the +following script: [source,js] -------------------------------------------------- @@ -45,8 +111,8 @@ POST test/_update/1 // CONSOLE // TEST[continued] -We can add a tag to the list of tags (if the tag exists, it - still gets added, since this is a list): +Similarly, you could use and update script to add a tag to the list of tags +(this is just a list, so the tag is added even it exists): [source,js] -------------------------------------------------- @@ -64,11 +130,11 @@ POST test/_update/1 // CONSOLE // TEST[continued] -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: +You could also remove a tag from the list of tags. The Painless +function to `remove` a tag takes the array index of the element +you want to remove. To avoid a possible runtime error, you first need to +make sure the tag exists. If the list contains duplicates of the tag, this +script just removes one occurrence. [source,js] -------------------------------------------------- @@ -86,11 +152,8 @@ POST test/_update/1 // CONSOLE // TEST[continued] -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: +You can also add and remove fields from a document. For example, this script +adds the field `new_field`: [source,js] -------------------------------------------------- @@ -102,7 +165,7 @@ POST test/_update/1 // CONSOLE // TEST[continued] -Or remove a field from the document: +Conversely, this script removes the field `new_field`: [source,js] -------------------------------------------------- @@ -114,9 +177,9 @@ POST test/_update/1 // CONSOLE // TEST[continued] -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`): +Instead of updating the document, you can also change the operation that is +executed from within the script. For example, this request deletes the doc if +the `tags` field contains `green`, otherwise it does nothing (`noop`): [source,js] -------------------------------------------------- @@ -135,13 +198,8 @@ POST test/_update/1 // TEST[continued] [float] -==== Updates with a partial document +===== Update part of a document -The 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 <> should -be used instead. The following partial update adds a new field to the existing document: @@ -157,14 +215,14 @@ POST test/_update/1 // CONSOLE // TEST[continued] -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. +If both `doc` and `script` are specified, then `doc` is ignored. If you +specify a scripted update, include the fields you want to update in the script. [float] -==== Detecting noop updates +===== Detect noop updates -If `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: +By default updates that don't change anything detect that they don't change +anything and return `"result": "noop"`: [source,js] -------------------------------------------------- @@ -178,9 +236,8 @@ POST test/_update/1 // CONSOLE // TEST[continued] -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. +If the value of `name` is already `new_name`, the update +request is ignored and the `result` element in the response returns `noop`: [source,js] -------------------------------------------------- @@ -201,7 +258,7 @@ the request was ignored. -------------------------------------------------- // TESTRESPONSE -You can disable this behavior by setting `"detect_noop": false` like this: +You can disable this behavior by setting `"detect_noop": false`: [source,js] -------------------------------------------------- @@ -218,11 +275,11 @@ POST test/_update/1 [[upserts]] [float] -==== Upserts +===== Upsert 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: +are inserted as a new document. If the document exists, the +`script` is executed: [source,js] -------------------------------------------------- @@ -245,11 +302,10 @@ POST test/_update/1 [float] [[scripted_upsert]] -===== `scripted_upsert` +===== 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`: +To run the script whether or not the document exists, set `scripted_upsert` to +`true`: [source,js] -------------------------------------------------- @@ -275,10 +331,10 @@ POST sessions/_update/dh3sgudg8gsrgl [float] [[doc_as_upsert]] -===== `doc_as_upsert` +===== 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` +Instead of sending a partial `doc` plus an `upsert` doc, you can set +`doc_as_upsert` to `true` to use the contents of `doc` as the `upsert` value: [source,js] @@ -293,51 +349,3 @@ POST test/_update/1 -------------------------------------------------- // CONSOLE // TEST[continued] - -[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. - -`timeout`:: - -Timeout waiting for a shard to become available. - -`wait_for_active_shards`:: - -The number of shard copies required to be active before proceeding with the update operation. -See <> for details. - -`refresh`:: - -Control when the changes made by this request are visible to search. See -<>. - -`_source`:: - -Allows to control if and how the updated source should be returned in the response. -By default the updated source is not returned. -See <> for details. - -`if_seq_no` and `if_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` and `if_primary_term` parameters. If a -mismatch is detected, the operation will result in a `VersionConflictException` -and a status code of 409. See <> for more details. \ No newline at end of file