Execute Painless script

Introduced 1.0

The Execute Painless script API allows you to run a script that is not stored.

Path and HTTP methods

  1. GET /_scripts/painless/_execute
  2. POST /_scripts/painless/_execute

Request fields

FieldDescription
scriptThe script to run. Required
contextA context for the script. Optional. Default is painless_test.
context_setupSpecifies additional parameters for the context. Optional.

Example request

The following request uses the default painless_context for the script:

  1. GET /_scripts/painless/_execute
  2. {
  3.   "script": {
  4.     "source": "(params.x + params.y)/ 2",
  5.     "params": {
  6.       "x": 80,
  7.       "y": 100
  8.     }
  9.   }
  10. }

copy

Example response

The response contains the average of two script parameters:

  1. {
  2.   "result" : "90"
  3. }

Response fields

FieldDescription
resultThe script result.

Script contexts

Choose different contexts to control the variables that are available to the script and the result’s return type. The default context is painless_test.

Painless test context

The painless_test context is the default script context that provides only the params variable to the script. The returned result is always converted to a string. See the preceding example request for a usage example.

Filter context

The filter context runs the script as if the script were inside a script query. You must provide a test document in the context. The _source, stored fields, and _doc variables will be available to the script.

You can specify the following parameters for the filter context in the context_setup.

ParameterDescription
documentThe document that is indexed in memory temporarily and available to the script.
indexThe name of the index that contains a mapping for the document.

For example, first create an index with a mapping for a test document:

  1. PUT /testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "grad": {
  6.         "type": "boolean"
  7.       },
  8.       "gpa": {
  9.         "type": "float"
  10.       }
  11.     }
  12.   }
  13. }

copy

Run a script to determine if a student is eligible to graduate with honors:

  1. POST /_scripts/painless/_execute
  2. {
  3.   "script": {
  4.     "source": "doc['grad'].value == true && doc['gpa'].value >= params.min_honors_gpa",
  5.     "params": {
  6.       "min_honors_gpa": 3.5
  7.     }
  8.   },
  9.   "context": "filter",
  10.   "context_setup": {
  11.     "index": "testindex1",
  12.     "document": {
  13.       "grad": true,
  14.       "gpa": 3.79
  15.     }
  16.   }
  17. }

copy

The response contains the result:

  1. {
  2.   "result" : true
  3. }

Score context

The score context runs a script as if the script were in a script_score function in a function_score query.

You can specify the following parameters for the score context in the context_setup.

ParameterDescription
documentThe document that is indexed in memory temporarily and available to the script.
indexThe name of the index that contains a mapping for the document.
queryIf the script uses the _score parameter, the query can specify to use the _score field to compute the score.

For example, first create an index with a mapping for a test document:

  1. PUT /testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "gpa_4_0": {
  6.         "type": "float"
  7.       }
  8.     }
  9.   }
  10. }

copy

Run a script that converts a GPA on a 4.0 scale into a different scale that is provided as a parameter:

  1. POST /_scripts/painless/_execute
  2. {
  3.   "script": {
  4.     "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0",
  5.     "params": {
  6.       "max_gpa": 5.0
  7.     }
  8.   },
  9.   "context": "score",
  10.   "context_setup": {
  11.     "index": "testindex1",
  12.     "document": {
  13.       "gpa_4_0": 3.5
  14.     }
  15.   }
  16. }

copy

The response contains the result:

  1. {
  2.   "result" : 4.375
  3. }