Specify usage of upsert key in Bulk operations

_api-reference/document-apis/bulk.md

@@ -98,12 +98,20 @@ By default, this action updates existing documents and returns an error if the d
 
 ### Upsert
 
-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:
+To upsert a document, either:
+1. Specify the document in the `doc` field, and set `doc_as_upsert=true`. If the document exists, it is updated with the contents of the `doc` field; if it does not exist, a new document is indexed with the parameters specified in the `doc` field.
 
 ```json
 { "update": { "_index": "movies", "_id": "tt0816711" } }
 { "doc" : { "title": "World War Z" }, "doc_as_upsert": true }
 ```
+2. Or specify the document to be updated (if the document exists) in the `doc` field , and the document to be upserted (if the document doesn't exist) in the `upsert` field, and leave `doc_as_update` as `false`.
+This is best used in the scenario where you only want to update only specific fields when a document exists, but insert a complete document when it doesn't exist.
+
+```
+{ "update": { "_index": "products", "_id": "widget-123" } }
+{ "doc": { "stock": 75, "updated_at": "2025-01-15T10:30:00Z" }, "upsert": { "name": "Widget", "price": 39.99, "stock": 100, "created_at": "2025-01-15T10:30:00Z" }}
+```
 
 ### Script
 
@@ -116,15 +124,26 @@ You can specify a script for more complex document updates by defining the scrip
 
 ### Scripted upsert
 
-You can use a script to insert or update a document in one operation by setting `scripted_upsert` to `true`. This ensures that the script runs whether or not the document exists. If the document does not exist, the script initializes its content from scratch.
+You can use a script to update or upsert a document.
+
+
+1. Script + Upsert (scripted_upsert=false, default). If the document exists, update the document using the `script`. If the document does not,  upsert the document in the `upsert` field (without running the script)
+
+```
+POST _bulk
+{ "update": { "_index": "movies", "_id": "tt0816711" } }
+{ "script": { "source": "ctx._source.title = params.title; ctx._source.genre = params.genre;", "params": { "title": "World War Z", "genre": "Action" } }, "upsert": { "title": "World War Z", "genre": "Action", "author": "Tom Smith" } }
+`
+```
+
+2. Script + Upsert + scripted_upsert=true. If the document exists, update the document using the `script`. If the document does not, run the script on the `upsert` field then upsert the document.
 
 ```json
 POST _bulk
 { "update": { "_index": "movies", "_id": "tt0816711" } }
-{ "script": { "source": "ctx._source.title = params.title; ctx._source.genre = params.genre;", "params": { "title": "World War Z", "genre": "Action" } }, "upsert": {}, "scripted_upsert": true }
+{ "script": { "source": "ctx._source.title = params.title; ctx._source.genre = params.genre;", "params": { "title": "World War Z", "genre": "Action" } }, "scripted_upsert": true }
 ```
 
-This operation creates a new document if one with ID `tt0816711` does not exist, using the logic in the script. If the document does exist, the same script is applied to update its fields.
 
 ## Example request