Execute Inline Script API

Introduced 1.0

The Execute Inline Script API allows you to run a script directly without storing it in the cluster state. The script is compiled and executed each time the API is called.

Endpoints

GET /_scripts/painless/_execute POST /_scripts/painless/_execute 

Request body fields

Example request

POST /_scripts/painless/_execute { "script": { "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", "params": { "max_gpa": 5.0 } }, "context": "score", "context_setup": { "index": "testindex1", "document": { "gpa_4_0": 3.5 } } }

response = client.put_script( id = "painless", context = "_execute", body = { "script": { "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", "params": { "max_gpa": 5.0 } }, "context": "score", "context_setup": { "index": "testindex1", "document": { "gpa_4_0": 3.5 } } } )

The following request uses the default painless_context for the script:

GET /_scripts/painless/_execute { "script": { "source": "(params.x + params.y)/ 2", "params": { "x": 80, "y": 100 } } }

response = client.scripts_painless_execute( body = { "script": { "source": "(params.x + params.y)/ 2", "params": { "x": 80, "y": 100 } } } )

Example response

The response contains the average of two script parameters:

{ "result" : "90" } 

Response body fields

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.

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

PUT /testindex1 { "mappings": { "properties": { "grad": { "type": "boolean" }, "gpa": { "type": "float" } } } } 

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

POST /_scripts/painless/_execute { "script": { "source": "doc['grad'].value == true && doc['gpa'].value >= params.min_honors_gpa", "params": { "min_honors_gpa": 3.5 } }, "context": "filter", "context_setup": { "index": "testindex1", "document": { "grad": true, "gpa": 3.79 } } }

response = client.put_script( id = "painless", context = "_execute", body = { "script": { "source": "doc['grad'].value == true && doc['gpa'].value >= params.min_honors_gpa", "params": { "min_honors_gpa": 3.5 } }, "context": "filter", "context_setup": { "index": "testindex1", "document": { "grad": true, "gpa": 3.79 } } } )

The response contains the result:

{ "result" : true } 

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.

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

PUT /testindex1 { "mappings": { "properties": { "gpa_4_0": { "type": "float" } } } } 

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

POST /_scripts/painless/_execute { "script": { "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", "params": { "max_gpa": 5.0 } }, "context": "score", "context_setup": { "index": "testindex1", "document": { "gpa_4_0": 3.5 } } }

response = client.put_script( id = "painless", context = "_execute", body = { "script": { "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", "params": { "max_gpa": 5.0 } }, "context": "score", "context_setup": { "index": "testindex1", "document": { "gpa_4_0": 3.5 } } } )

The response contains the result:

{ "result" : 4.375 }