173 lines
4.3 KiB
Plaintext
173 lines
4.3 KiB
Plaintext
[[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 do 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,js]
|
|
----------------------------------------------------------------
|
|
POST /_scripts/painless/_execute
|
|
{
|
|
"script": {
|
|
"source": "params.count / params.total",
|
|
"params": {
|
|
"count": 100.0,
|
|
"total": 1000.0
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"result": "0.1"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE
|
|
|
|
===== Filter context
|
|
|
|
The `filter` context executes scripts as if they were executed inside a `script` query.
|
|
For testing purposes a document must be provided that will be indexed temporarily in-memory and
|
|
is accessible to the script being tested. Because of this the _source, stored fields and doc values
|
|
are available in 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,js]
|
|
----------------------------------------------------------------
|
|
PUT /my-index
|
|
{
|
|
"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",
|
|
"document": {
|
|
"field": "four"
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"result": true
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE
|
|
|
|
|
|
===== 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 specified that will be used to compute a score.
|
|
|
|
*Example*
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------
|
|
PUT /my-index
|
|
{
|
|
"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",
|
|
"document": {
|
|
"rank": 4
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"result": 0.8
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE
|