Run a script Technical preview; Added in 6.3.0

POST /_scripts/painless/_execute
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_scripts/painless/_execute

POST /_scripts/painless/_execute

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.

application/json

Body

  • context string

    The context that the script should run in. NOTE: Result ordering in the field contexts is not guaranteed.

    Supported values include:

    • painless_test: The default context if no other context is specified.
    • filter: Treats scripts as if they were run inside a script query.
    • score: Treats scripts as if they were run inside a script_score function in a function_score query.
    • boolean_field: The context for boolean fields. The script returns a true or false response.
    • date_field: The context for date fields. emit takes a long value and the script returns a sorted list of dates.
    • double_field: The context for double numeric fields. The script returns a sorted list of double values.
    • geo_point_field: The context for geo-point fields. emit takes two double parameters, the latitude and longitude values, and the script returns an object in GeoJSON format containing the coordinates for the geo point.
    • ip_field: The context for ip fields. The script returns a sorted list of IP addresses.
    • keyword_field: The context for keyword fields. The script returns a sorted list of string values.
    • long_field: The context for long numeric fields. The script returns a sorted list of long values.
    • composite_field: The context for composite runtime fields. The script returns a map of values.

    Values are painless_test, filter, score, boolean_field, date_field, double_field, geo_point_field, ip_field, keyword_field, long_field, or composite_field.

  • context_setup object

    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.

    Hide context_setup attributes Show context_setup attributes object
    • document object Required

      Document that's temporarily indexed in-memory and accessible from the script.

    • index string Required

      Index containing a mapping that's compatible with the indexed document. You may specify a remote index by prefixing the index with the remote cluster alias. For example, remote1:my_index indicates that you want to run the painless script against the "my_index" index on the "remote1" cluster. This request will be forwarded to the "remote1" cluster if you have configured a connection to that remote cluster.

      NOTE: Wildcards are not accepted in the index expression for this endpoint. The expression *:myindex will return the error "No such remote cluster" and the expression logs* or remote1:logs* will return the error "index not found".

    • query object

      Use this parameter to specify a query for computing a score.

      External documentation
  • script object

    The Painless script to run.

    Hide script attributes Show script attributes object
    • source string

      The script source.

    • id string

      The id for a stored script.

    • params object

      Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

      Hide params attribute Show params attribute object
      • * object Additional properties

    • lang string

      Specifies the language the script is written in.

      Supported values include:

      • painless: Painless scripting language, purpose-built for Elasticsearch.
      • expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.
      • mustache: Mustache templated, used for templates.
      • java: Expert Java API
      Any of:
      string-1 string string-2 string

      Specifies the language the script is written in.

      Supported values include:

      • painless: Painless scripting language, purpose-built for Elasticsearch.
      • expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.
      • mustache: Mustache templated, used for templates.
      • java: Expert Java API

      Values are painless, expression, mustache, or java.

      Specifies the language the script is written in.

      Supported values include:

      • painless: Painless scripting language, purpose-built for Elasticsearch.
      • expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.
      • mustache: Mustache templated, used for templates.
      • java: Expert Java API
    • options object
      Hide options attribute Show options attribute object
      • * string Additional properties

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result object Required
POST /_scripts/painless/_execute 
POST /_scripts/painless/_execute { "script": { "source": "params.count / params.total", "params": { "count": 100.0, "total": 1000.0 } } }
resp = client.scripts_painless_execute( script={ "source": "params.count / params.total", "params": { "count": 100, "total": 1000 } }, )
const response = await client.scriptsPainlessExecute({ script: { source: "params.count / params.total", params: { count: 100, total: 1000, }, }, });
response = client.scripts_painless_execute( body: { "script": { "source": "params.count / params.total", "params": { "count": 100, "total": 1000 } } } )
$resp = $client->scriptsPainlessExecute([ "body" => [ "script" => [ "source" => "params.count / params.total", "params" => [ "count" => 100, "total" => 1000, ], ], ], ]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"script":{"source":"params.count / params.total","params":{"count":100,"total":1000}}}' "$ELASTICSEARCH_URL/_scripts/painless/_execute"
client.scriptsPainlessExecute(s -> s .script(sc -> sc .source(so -> so .scriptString("params.count / params.total") ) .params(Map.of("total", JsonData.fromJson("1000"),"count", JsonData.fromJson("100"))) ) );
Request examples
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. 
{ "script": { "source": "params.count / params.total", "params": { "count": 100.0, "total": 1000.0 } } }
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. 
{ "script": { "source": "doc['field'].value.length() <= params.max_length", "params": { "max_length": 4 } }, "context": "filter", "context_setup": { "index": "my-index-000001", "document": { "field": "four" } } }
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. 
{ "script": { "source": "doc['rank'].value / params.max_rank", "params": { "max_rank": 5.0 } }, "context": "score", "context_setup": { "index": "my-index-000001", "document": { "rank": 4 } } }
Response examples (200)
A successful response from `POST /_scripts/painless/_execute` with a `painless_test` context. 
{ "result": "0.1" }
A successful response from `POST /_scripts/painless/_execute` with a `filter` context. 
{ "result": true }
A successful response from `POST /_scripts/painless/_execute` with a `score` context. 
{ "result": 0.8 }