add pages

Author: kilfoyle

docs/reference/images/painless/painless-method-dispatching.png

@@ -8,15 +8,48 @@ products:
   - id: painless
 ---
 
-# How painless dispatches function [modules-scripting-painless-dispatch]
+# Understanding method dispatching in Painless [modules-scripting-painless-dispatch]
 
-Painless uses receiver, name, and [arity](https://en.wikipedia.org/wiki/Arity) for method dispatch. For example, `s.foo(a, b)` is resolved by first getting the class of `s` and then looking up the method `foo` with two parameters. This is different from Groovy which uses the [runtime types](https://en.wikipedia.org/wiki/Multiple_dispatch) of the parameters and Java which uses the compile time types of the parameters.
+Painless uses a function dispatch mechanism based on the receiver, method name, and [arity](https://en.wikipedia.org/wiki/Arity) (number of parameters). This approach differs from Java, which dispatches based on compiled-time types, and Groovy, which uses [runtime types](https://en.wikipedia.org/wiki/Multiple_dispatch). Understanding this mechanism is fundamental when migrating scripts or interacting with Java standard library APIs from Painless, as it helps you avoid common errors and write more efficient, secure scripts.
 
-The consequence of this that Painless doesn’t support overloaded methods like Java, leading to some trouble when it allows classes from the Java standard library. For example, in Java and Groovy, `Matcher` has two methods: `group(int)` and `group(String)`. Painless can’t allow both of these methods because they have the same name and the same number of parameters. So instead it has `group(int)` and `namedGroup(String)`.
+## Key terms
+
+Before diving into the dispatch process, here a brief definition of the main concepts:
+
+* **Receiver:** The object or class on which the method is called. For example, in `s.foo(a, b)` the variable `s` is the receiver  
+* **Name:** The name of the method being invoked, such as `foo` in `s.foo(a, b)`  
+* **Arity:** The number of parameters the method accepts. In `s.foo(a, b)` the arity is 2  
+* **Dispatch:** The process of determining which method implementation to execute based on the receiver, name, and arity
+
+:::{image} ../../images/painless/painless-method-dispatching.png
+:alt: Flowchart showing five steps: s.foo, receiver, name, arity, and execute method
+:width: 250px
+:::
+
+## Why method dispatch matters
+
+This fundamental difference affects how you work with Java APIs in your scripts. When translating Java code to Painless, methods you expect from the standard library might have different names or behave differently. Understanding method dispatch helps you avoid common errors and write more efficient scripts, particularly when working with `def` types that benefit from this optimized resolution mechanism.
+
+## Impact on Java standard library usage
+
+The consequence of the different approach used by Painless is that Painless doesn’t support overload methods like Java, leading to some trouble when it allows classes from the Java standard library. For example, in Java and Groovy, `Matcher` has two methods:
+
+* `group(int)`  
+* `group(string)`
+
+Painless can’t allow both of these methods because they have the same name and the same number of parameters. Instead, it has `group(int)` and `namedGroup(String)`. If you try to call a method that is not exposed in Painless, you will get a compilation error. 
+
+This renaming pattern occurs throughout the Painless API when adapting Java standard library classes. Any methods that would conflict due to identical names and parameter counts receive distinct names in Painless to ensure unambiguous method resolution.
+
+## Justification for this approach
 
 We have a few justifications for this different way of dispatching methods:
 
-1. It makes operating on `def` types simpler and, presumably, faster. Using receiver, name, and arity means that when Painless sees a call on a `def` object it can dispatch the appropriate method without having to do expensive comparisons of the types of the parameters. The same is true for invocations with `def` typed parameters.
-2. It keeps things consistent. It would be genuinely weird for Painless to behave like Groovy if any `def` typed parameters were involved and Java otherwise. It’d be slow for it to behave like Groovy all the time.
-3. It keeps Painless maintainable. Adding the Java or Groovy like method dispatch **feels** like it’d add a ton of complexity which’d make maintenance and other improvements much more difficult.
+1. It makes operating on `def` types simpler and, presumably, faster. Using receiver, name and arity means that when Painless sees a call on a `def` object it can dispatch the appropriate method without having to do expensive comparisons of the types of the parameters. The same is true for invocation with `def` typed parameters.  
+2. It keeps things consistent. It would be genuinely weird for Painless to behave like Groovy if any `def` typed parameters were involved and Java otherwise. It’d be slow for Painless to behave like Groovy all the time.   
+3. It keeps Painless maintainable. Adding the Java or Groovy like method dispatch **feels** like it’d add a lot of complexity, which would make maintenance and other improvements much more difficult.
+
+## Next steps
+
+For more details, view the [Painless language specification](/reference/scripting-languages/painless/painless-language-specification.md) and the [Painless API examples](/reference/scripting-languages/painless/painless-api-examples.md).
 

docs/reference/scripting-languages/painless/how-painless-dispatches-function.md

@@ -8,15 +8,61 @@ products:
   - id: painless
 ---
 
-# Painless API examples [painless-execute-api]
+# Painless execute API [painless-execute-api]
 
 ::::{warning}
 This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
 ::::
 
-
 The Painless execute API runs a script and returns a result.
 
+## Description
+
+Use this API to build and test scripts, such as when defining a script for a [runtime field](docs-content://manage-data/data-store/mapping/runtime-fields.md). This API requires very few dependencies and is especially useful if you don’t have the required permissions to write documents to a cluster. 
+
+## How it works
+
+The Painless execute API runs scripts in an isolated execution environment and returns results for development and testing purposes. The request body must include a `script` object, and additional parameters may be required depending on the selected context. For example, providing a `context_setup` parameter allows you to add a document to execute the script against.
+
+The API executes the script within the {{es}} Painless engine and does not perform write operations or modify indexed documents.
+
+## Supported contexts
+
+The API supports the following contexts for script execution:
+
+### Test context (`test`)
+
+Test scripts without additional parameters or context settings. Only the `params` variable is available, and results are always converted to a string. This is the default context when no other is specified.
+
+### Filter context (`filter`)
+
+Test scripts that return boolean values, such as those used in script queries for field comparisons or value checks. Scripts run as if inside a `script` query and have access to `_source`, stored fields, and doc values of the provided document.
+
+### Score context (`score`)
+
+Validate custom scoring functions for `function_score` queries, such as ranking calculations based on field values. Scripts run as if inside a `script_score` function and can access document fields for scoring calculations.
+
+### Field contexts
+
+Test field context scripts using the `emit` function for runtime fields:
+
+* `boolean_field`: Return `true` or `false` values for boolean field types.  
+* `date_field`: Process and emit date values as long timestamps.  
+* `double_field`: Return sorted lists of double numeric values.  
+* `geo_point_field`: Emit latitude and longitude coordinates for geo-point fields.  
+* `ip_fields`: Process and return IP addresses from text data.  
+* `keyword_field`: Return sorted lists of string values.  
+* `long_field`: Return sorted lists of long numeric values.  
+* `composite_field`: Return maps of values for composite runtime fields.
+
+## When to use the Painless execute API
+
+Use the Painless execute API in the following scenarios:
+
+* To test script syntax and logic before deploying to production.  
+* When you do not have write permissions on a live cluster.  
+* To validate script behavior using specific test data.
+
 ## {{api-request-title}} [painless-execute-api-request]
 
 `POST /_scripts/painless/_execute`
@@ -859,6 +905,3 @@ The response includes the values that the script emitted:
   }
 }
 ```
-
-
-