Run a script Technical preview

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

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

    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
    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
    • query object

      An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

      External documentation
  • script object
    Hide script attributes Show script attributes object

    • source string | object

      One of:
      ScriptSource string SearchRequestBody object
    • id string
    • 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

      Any of:
      ScriptLanguage string ScriptLanguage string

      Values are painless, expression, mustache, or java.

    • options object
      Hide options attribute Show options attribute object
      • * string Additional properties

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
POST /_scripts/painless/_execute 
POST /_scripts/painless/_execute
{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}
curl \
 --request POST 'http://api.example.com/_scripts/painless/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"script\": {\n    \"source\": \"params.count / params.total\",\n    \"params\": {\n      \"count\": 100.0,\n      \"total\": 1000.0\n    }\n  }\n}"'
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
}