From f5797b2dcafb9da767423c666df47a674ed7e19c Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Sat, 10 Aug 2019 12:39:09 -0700 Subject: [PATCH 1/4] [DOCS] Reformat update API reference. --- docs/reference/docs/update.asciidoc | 68 +++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 14 deletions(-) diff --git a/docs/reference/docs/update.asciidoc b/docs/reference/docs/update.asciidoc index c0cc88bb4f5e7..a61eb0d77f67c 100644 --- a/docs/reference/docs/update.asciidoc +++ b/docs/reference/docs/update.asciidoc @@ -1,18 +1,61 @@ [[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. +[[update-api-desc]] +==== {api-description-title} -For example, let's index a simple doc: +Enables you script document updates. This operation: + +. Gets the document (collocated with the shard) from the index. +. Runs the specified script. +. Indexes the result. + +The script can update, delete, or skip modifying the document. + +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`. + +[[docs-update-api-query-params]] +==== {api-query-parms-title} + +`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-routing] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source-excludes] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source-includes] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term] + +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,9 +67,6 @@ PUT test/_doc/1 -------------------------------------------------- // CONSOLE -[float] -==== Scripted updates - Now, we can execute a script that would increment the counter: [source,js] @@ -340,4 +380,4 @@ 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 +and a status code of 409. See <> for more details. From 69078b07452e3cb9e0ccd68d3b98702eb8a3e4c0 Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Mon, 12 Aug 2019 16:02:55 -0700 Subject: [PATCH 2/4] Edits to sync with Index API. --- docs/reference/docs/update.asciidoc | 171 +++++++++++----------------- 1 file changed, 65 insertions(+), 106 deletions(-) diff --git a/docs/reference/docs/update.asciidoc b/docs/reference/docs/update.asciidoc index a61eb0d77f67c..456fc966e230e 100644 --- a/docs/reference/docs/update.asciidoc +++ b/docs/reference/docs/update.asciidoc @@ -6,22 +6,6 @@ Updates a document using the specified script. -[[update-api-desc]] -==== {api-description-title} - -Enables you script document updates. This operation: - -. Gets the document (collocated with the shard) from the index. -. Runs the specified script. -. Indexes the result. - -The script can update, delete, or skip modifying the document. - -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`. [[docs-update-api-query-params]] ==== {api-query-parms-title} @@ -35,6 +19,14 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh] (Optional, integer) Specify how many times should the operation be retried when a conflict occurs. Default: 0. + 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. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh] + include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing] include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source] @@ -52,6 +44,30 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term] include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards] +[[update-api-desc]] +==== {api-description-title} + +Enables you script document updates. This operation: + +. Gets the document (collocated with the shard) from the index. +. Runs the specified script. +. Indexes the result. + +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 <> instead. + +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). + + [[update-api-example]] ==== {api-examples-title} @@ -67,7 +83,8 @@ PUT test/_doc/1 -------------------------------------------------- // CONSOLE -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] -------------------------------------------------- @@ -85,8 +102,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] -------------------------------------------------- @@ -104,11 +121,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] -------------------------------------------------- @@ -126,11 +143,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] -------------------------------------------------- @@ -142,7 +156,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] -------------------------------------------------- @@ -154,9 +168,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] -------------------------------------------------- @@ -175,13 +189,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: @@ -197,14 +206,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] -------------------------------------------------- @@ -218,9 +227,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] -------------------------------------------------- @@ -241,7 +249,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] -------------------------------------------------- @@ -258,11 +266,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] -------------------------------------------------- @@ -285,11 +293,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] -------------------------------------------------- @@ -315,10 +322,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] @@ -333,51 +340,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. From 1e8760bd6f474b8ee36b07c87d77f274b8bc88fe Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Mon, 12 Aug 2019 16:59:28 -0700 Subject: [PATCH 3/4] Added missing path parms --- docs/reference/docs/index_.asciidoc | 2 +- docs/reference/docs/update.asciidoc | 53 +++++++++++++++++------------ 2 files changed, 33 insertions(+), 22 deletions(-) diff --git a/docs/reference/docs/index_.asciidoc b/docs/reference/docs/index_.asciidoc index 462755adfe1e1..465c62371cd36 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 456fc966e230e..0ed729596f89c 100644 --- a/docs/reference/docs/update.asciidoc +++ b/docs/reference/docs/update.asciidoc @@ -6,10 +6,28 @@ Updates a document using the specified script. +[[docs-update-api-request]] +==== {api-request-title} + +`POST /` + +[[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`. @@ -19,46 +37,39 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh] (Optional, integer) Specify how many times should the operation be retried when a conflict occurs. Default: 0. - 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. - include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh] include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing] -include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source] +`_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. -include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source-excludes] +`_source_excludes`:: +(Optional, list) Specify the source fields you want to exclude. -include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-source-includes] +`_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-seq-no] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term] - include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards] [[update-api-desc]] ==== {api-description-title} -Enables you script document updates. This operation: +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 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 <> instead. - 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. @@ -266,7 +277,7 @@ POST test/_update/1 [[upserts]] [float] -==== Upsert +===== Upsert If the document does not already exist, the contents of the `upsert` element are inserted as a new document. If the document exists, the From 55ab6a4571a4128fac0bc5c0296621644f19cffa Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Tue, 13 Aug 2019 09:37:21 -0700 Subject: [PATCH 4/4] Moved description where it belongs. --- docs/reference/docs/update.asciidoc | 46 ++++++++++++++--------------- 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/reference/docs/update.asciidoc b/docs/reference/docs/update.asciidoc index 0ed729596f89c..1a732cf1246be 100644 --- a/docs/reference/docs/update.asciidoc +++ b/docs/reference/docs/update.asciidoc @@ -11,6 +11,28 @@ Updates a document using the specified script. `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} @@ -55,30 +77,6 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards] - -[[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). - - [[update-api-example]] ==== {api-examples-title}