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
}