OpenSearch/docs/painless/painless-guide/painless-execute-script.asciidoc

[[painless-execute-api]]
=== Painless execute API

experimental[The painless execute api is new and the request / response format may change in a breaking way in the future]

The Painless execute API allows an arbitrary script to be executed and a result to be returned.

[[painless-execute-api-parameters]]
.Parameters
[options="header"]
|======
| Name              | Required  | Default                | Description
| `script`          | yes       | -                      | The script to execute.
| `context`         | no        | `painless_test`        | The context the script should be executed in.
| `context_setup`   | no        | -                      | Additional parameters to the context.
|======

==== Contexts

Contexts control how scripts are executed, what variables are available at runtime and what the return type is.

===== Painless test context

The `painless_test` context executes scripts as is and does not add any special 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.
If no context is specified then this context is used by default.

*Example*

Request:

[source,console]
----------------------------------------------------------------
POST /_scripts/painless/_execute
{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": "0.1"
}
--------------------------------------------------

===== Filter context

The `filter` context executes scripts as if they were executed 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.

The following parameters may be specified in `context_setup` for a filter context:

document:: Contains the document that will be temporarily indexed in-memory and is accessible from the script.
index:: The name of an index containing a mapping that is compatible with the document being indexed.

*Example*

[source,console]
----------------------------------------------------------------
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "field": {
        "type": "keyword"
      }
    }
  }
}

POST /_scripts/painless/_execute
{
  "script": {
    "source": "doc['field'].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "field": "four"
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": true
}
--------------------------------------------------


===== Score context

The `score` context executes scripts as if they were executed inside a `script_score` function in
`function_score` query.

The following parameters may be specified in `context_setup` for a score context:

document:: Contains the document that will be temporarily indexed in-memory and is accessible from the script.
index:: The name of an index containing a mapping that is compatible with the document being indexed.
query:: If `_score` is used in the script then a query can specify that it will be used to compute a score.

*Example*

[source,console]
----------------------------------------------------------------
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "field": {
        "type": "keyword"
      },
      "rank": {
        "type": "long"
      }
    }
  }
}


POST /_scripts/painless/_execute
{
  "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:

[source,console-result]
--------------------------------------------------
{
  "result": 0.8
}
--------------------------------------------------