Update the Update and Bulk API's update/upsert sections (#6182)

* Update the Update API and upsert operation

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

---------

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Co-authored-by: Nathan Bower <nbower@amazon.com>

_api-reference/cat/cat-nodes.md

@@ -1,8 +1,7 @@
 ---
 layout: default
-title: CAT nodes operation
+title: CAT nodes
 parent: CAT API
-
 nav_order: 40
 has_children: false
 redirect_from:

_api-reference/document-apis/bulk.md

@@ -82,7 +82,7 @@ All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If
 
 - Create
 
-  Creates a document if it doesn't already exist and returns an error otherwise. The next line must include a JSON document.
+  Creates a document if it doesn't already exist and returns an error otherwise. The next line must include a JSON document:
 
   ```json
   { "create": { "_index": "movies", "_id": "tt1392214" } }
@@ -91,7 +91,7 @@ All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If
 
 - Delete
 
-  This action deletes a document if it exists. If the document doesn't exist, OpenSearch doesn't return an error, but instead returns `not_found` under `result`. Delete actions don't require documents on the next line.
+  This action deletes a document if it exists. If the document doesn't exist, OpenSearch doesn't return an error but instead returns `not_found` under `result`. Delete actions don't require documents on the next line:
 
   ```json
   { "delete": { "_index": "movies", "_id": "tt2229499" } }
@@ -99,7 +99,7 @@ All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If
 
 - Index
 
-  Index actions create a document if it doesn't yet exist and replace the document if it already exists. The next line must include a JSON document.
+  Index actions create a document if it doesn't yet exist and replace the document if it already exists. The next line must include a JSON document:
 
   ```json
   { "index": { "_index": "movies", "_id": "tt1979320" } }
@@ -108,20 +108,14 @@ All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If
 
 - Update
 
-  This action updates existing documents and returns an error if the document doesn't exist. The next line must include a full or partial JSON document, depending on how much of the document you want to update.
+  By default, this action updates existing documents and returns an error if the document doesn't exist. The next line must include a full or partial JSON document, depending on how much of the document you want to update:
 
   ```json
   { "update": { "_index": "movies", "_id": "tt0816711" } }
   { "doc" : { "title": "World War Z" } }
   ```
 
-  It can also include a script or upsert for more complex document updates.
-
-  - Script
-  ```json
-  { "update": { "_index": "movies", "_id": "tt0816711" } }
-  { "script" : { "source": "ctx._source.title = \"World War Z\"" } }
-  ```
+  To upsert a document, specify `doc_as_upsert` as `true`. If a document exists, it is updated; if it does not exist, a new document is indexed with the parameters specified in the `doc` field: 
 
   - Upsert
   ```json
@@ -129,6 +123,14 @@ All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If
   { "doc" : { "title": "World War Z" }, "doc_as_upsert": true }
   ```
 
+  You can specify a script for more complex document updates:
+
+  - Script
+  ```json
+  { "update": { "_index": "movies", "_id": "tt0816711" } }
+  { "script" : { "source": "ctx._source.title = \"World War Z\"" } }
+  ```
+
 ## Response
 
 In the response, pay particular attention to the top-level `errors` boolean. If true, you can iterate over the individual actions for more detailed information.

_api-reference/document-apis/update-document.md

@@ -11,7 +11,7 @@ redirect_from:
 **Introduced 1.0**
 {: .label .label-purple }
 
-If you need to update a document's fields in your index, you can use the update document API operation. You can do so by specifying the new data you want in your index or by including a script in your request body, which OpenSearch runs to update the document.
+If you need to update a document's fields in your index, you can use the update document API operation. You can do so by specifying the new data you want to be in your index or by including a script in your request body, which OpenSearch runs to update the document. By default, the update operation only updates a document that exists in the index. If a document does not exist, the API returns an error. To _upsert_ a document (update the document that exists or index a new one), use the [upsert](#upsert) operation.
 
 ## Example
 
@@ -65,7 +65,7 @@ wait_for_active_shards | String | The number of active shards that must be avail
 
 ## Request body
 
-Your request body must contain the information you want to update your document with. If you just want to replace certain fields in your document, your request body must include a `doc` object, which has the fields you want to update.
+Your request body must contain the information with which you want to update your document. If you only want to replace certain fields in your document, your request body must include a `doc` object containing the fields that you want to update:
 
 ```json
 {
@@ -76,7 +76,7 @@ Your request body must contain the information you want to update your document
 }
 ```
 
-You can also use a script to tell OpenSearch how to update your document.
+You can also use a script to tell OpenSearch how to update your document:
 
 ```json
 {
@@ -90,11 +90,14 @@ You can also use a script to tell OpenSearch how to update your document.
 }
 ```
 
-### Upsert
+## Upsert
 
-Upsert is an operation that conditionally either updates an existing document or inserts a new one based on information in the object. In the following example, the `upsert` operation updates the `last name` and adds the `first_name` field if a document already exists. If a document does not exist, a new one is indexed using content in the `upsert` object.
+Upsert is an operation that conditionally either updates an existing document or inserts a new one based on information in the object. 
+
+In the following example, the `upsert` operation updates the `first_name` and `last_name` fields if a document already exists. If a document does not exist, a new one is indexed using content in the `upsert` object.
 
 ```json
+POST /sample-index1/_update/1
 {
   "doc": {
     "first_name": "Martha",
@@ -106,9 +109,53 @@ Upsert is an operation that conditionally either updates an existing document or
   }
 }
 ```
-You can also add `doc_as_upsert` to the request and set it to `true` to use the information in `doc` for performing the upsert operation.
+
+Consider an index that contains the following document:
 
 ```json
+{
+  "_index": "sample-index1",
+  "_id": "1",
+  "_score": 1,
+  "_source": {
+    "first_name": "Bruce",
+    "last_name": "Wayne"
+  }
+}
+```
+
+After the upsert operation, the document's `first_name` and `last_name` fields are updated:
+
+```json
+{
+  "_index": "sample-index1",
+  "_id": "1",
+  "_score": 1,
+  "_source": {
+    "first_name": "Martha",
+    "last_name": "Rivera"
+  }
+}
+```
+
+If the document does not exist in the index, a new document is indexed with the fields specified in the `upsert` object:
+
+```json
+{
+  "_index": "sample-index1",
+  "_id": "1",
+  "_score": 1,
+  "_source": {
+    "last_name": "Oliveira",
+    "age": "31"
+  }
+}
+```
+
+You can also add `doc_as_upsert` to the request and set it to `true` to use the information in the `doc` field for performing the upsert operation:
+
+```json
+POST /sample-index1/_update/1
 {
   "doc": {
     "first_name": "Martha",
@@ -119,6 +166,35 @@ You can also add `doc_as_upsert` to the request and set it to `true` to use the
 }
 ```
 
+Consider an index that contains the following document:
+
+```json
+{
+  "_index": "sample-index1",
+  "_id": "1",
+  "_score": 1,
+  "_source": {
+    "first_name": "Bruce",
+    "last_name": "Wayne"
+  }
+}
+```
+
+After the upsert operation, the document's `first_name` and `last_name` fields are updated and an `age` field is added. If the document does not exist in the index, a new document is indexed with the fields specified in the `upsert` object. In both cases, the document is as follows:
+
+```json
+{
+  "_index": "sample-index1",
+  "_id": "1",
+  "_score": 1,
+  "_source": {
+    "first_name": "Martha",
+    "last_name": "Oliveira",
+    "age": "31"
+  }
+}
+```
+
 ## Response
 ```json
 {