Augment painless execute API (#3589)

(cherry picked from commit 374de63)

specification/_global/scripts_painless_execute/ExecutePainlessScriptRequest.ts

@@ -19,15 +19,23 @@
 
 import { RequestBase } from '@_types/Base'
 import { Script } from '@_types/Scripting'
-import { PainlessContextSetup } from './types'
+import { PainlessContext, PainlessContextSetup } from './types'
 
 /**
  * Run a script.
+ *
  * Runs a script and returns a result.
+ * Use this API to build and test scripts, such as when defining a script for a runtime field.
+ * This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
+ *
+ * The API uses several _contexts_, which control how scripts are run, what variables are available at runtime, and what the return type is.
+ *
+ * Each context requires a script, but additional parameters depend on the context you're using for that script.
  * @rest_spec_name scripts_painless_execute
  * @availability stack since=6.3.0 stability=experimental
  * @availability serverless stability=experimental visibility=public
  * @doc_tag script
+ * @doc_id painless-execute-api
  */
 export interface Request extends RequestBase {
   urls: [
@@ -39,15 +47,17 @@ export interface Request extends RequestBase {
   body: {
     /**
      * The context that the script should run in.
+     * NOTE: Result ordering in the field contexts is not guaranteed.
      * @server_default painless_test
      */
-    context?: string
+    context?: PainlessContext
     /**
      * Additional parameters for the `context`.
+     * NOTE: This parameter is required for all contexts except `painless_test`, which is the default if no value is provided for `context`.
      */
     context_setup?: PainlessContextSetup
     /**
-     * The Painless script to execute.
+     * The Painless script to run.
      */
     script?: Script
   }

specification/_global/scripts_painless_execute/examples/request/ExecutePainlessScriptRequestExample1.yaml

@@ -0,0 +1,19 @@
+summary: Test context
+# method_request: POST /_scripts/painless/_execute
+description: >
+  Run `POST /_scripts/painless/_execute`.
+  The `painless_test` context is the default context.
+  It runs scripts without additional parameters.
+  The only variable that is available is `params`, which can be used to access user defined values.
+  The result of the script is always converted to a string.
+# type: request
+value: |-
+  {
+    "script": {
+      "source": "params.count / params.total",
+      "params": {
+        "count": 100.0,
+        "total": 1000.0
+      }
+    }
+  }

specification/_global/scripts_painless_execute/examples/request/ExecutePainlessScriptRequestExample2.yaml

@@ -0,0 +1,24 @@
+summary: Filter context
+# method_request: POST /_scripts/painless/_execute
+description: >
+  Run `POST /_scripts/painless/_execute` with a `filter` context.
+  It treats scripts as if they were run inside a script query.
+  For testing purposes, a document must be provided so that it will be temporarily indexed in-memory and is accessible from the script.
+  More precisely, the `_source`, stored fields, and doc values of such a document are available to the script being tested.
+# type: request
+value: |-
+  {
+    "script": {
+      "source": "doc['field'].value.length() <= params.max_length",
+      "params": {
+        "max_length": 4
+      }
+    },
+    "context": "filter",
+    "context_setup": {
+      "index": "my-index-000001",
+      "document": {
+        "field": "four"
+      }
+    }
+  }

specification/_global/scripts_painless_execute/examples/request/ExecutePainlessScriptRequestExample3.yaml

@@ -0,0 +1,22 @@
+summary: Score context
+# method_request: POST /_scripts/painless/_execute
+description: >
+  Run `POST /_scripts/painless/_execute` with a `score` context.
+  It treats scripts as if they were run inside a `script_score` function in a `function_score` query.
+# type: request
+value: |-
+  {
+    "script": {
+      "source": "doc['rank'].value / params.max_rank",
+      "params": {
+        "max_rank": 5.0
+      }
+    },
+    "context": "score",
+    "context_setup": {
+      "index": "my-index-000001",
+      "document": {
+        "rank": 4
+      }
+    }
+  }