Add painless context examples for update and update-by-query (#37943)

This commit improves the example docs for contexts in painless.

relates #34829

Author: rjernst

docs/build.gradle

@@ -1145,17 +1145,23 @@ buildRestTests.setups['seats'] = '''
                     type: keyword
                   cost:
                     type: long
+                  row:
+                    type: long
+                  number:
+                    type: long
+                  sold:
+                    type: boolean
   - do:
         bulk:
           index: seats
           type: _doc
           refresh: true
           body: |
-            {"index":{}}
-            {"theatre": "Skyline", "cost": 1}
-            {"index":{}}
-            {"theatre": "Graye", "cost": 5}
-            {"index":{}}
-            {"theatre": "Graye", "cost": 8}
-            {"index":{}}
-            {"theatre": "Skyline", "cost": 10}'''
+            {"index":{"_id": "1"}}
+            {"theatre": "Skyline", "cost": 37, "row": 1, "number": 7, "sold": false}
+            {"index":{"_id": "2"}}
+            {"theatre": "Graye", "cost": 30, "row": 3, "number": 5, "sold": false}
+            {"index":{"_id": "3"}}
+            {"theatre": "Graye", "cost": 33, "row": 2, "number": 6, "sold": false}
+            {"index":{"_id": "4"}}
+            {"theatre": "Skyline", "cost": 20, "row": 5, "number": 2, "sold": false}'''

docs/painless/painless-contexts/painless-update-by-query-context.asciidoc

@@ -51,4 +51,45 @@ result of query.
 
 *API*
 
-The standard <<painless-api-reference, Painless API>> is available.
+The standard <<painless-api-reference, Painless API>> is available.
+
+*Example*
+
+To run this example, first follow the steps in
+<<painless-context-examples, context examples>>.
+
+The following query finds all seats in a specific section that have not been
+sold and lowers the price by 2:
+
+[source,js]
+--------------------------------------------------
+POST /seats/_update_by_query
+{
+    "query": {
+        "bool": {
+            "filter": [
+            {
+                "range": {
+                    "row": {
+                        "lte": 3
+                    }
+                }
+            },
+            {
+                "match": {
+                    "sold": false
+                }
+            }]
+        }
+    },
+    "script": {
+        "source": "ctx._source.cost -= params.discount",
+        "lang": "painless",
+        "params": {
+            "discount": 2
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:seats]

docs/painless/painless-contexts/painless-update-context.asciidoc

@@ -52,4 +52,28 @@ add, modify, or delete fields within a single document.
 
 *API*
 
-The standard <<painless-api-reference, Painless API>> is available.
+The standard <<painless-api-reference, Painless API>> is available.
+
+*Example*
+
+To run this example, first follow the steps in
+<<painless-context-examples, context examples>>.
+
+The following query updates a document to be sold, and sets the cost
+to the actual price paid after discounts:
+
+[source,js]
+--------------------------------------------------
+POST /seats/_update/3
+{
+    "script": {
+        "source": "ctx._source.sold = true; ctx._source.cost = params.sold_cost",
+        "lang": "painless",
+        "params": {
+            "sold_cost": 26
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:seats]