mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-20 03:45:02 +00:00
1924f5d07c
This change adds two contexts the execute scripts against:
* SEARCH_SCRIPT: Allows to run scripts in a search script context.
This context is used in `function_score` query's script function,
script fields, script sorting and `terms_set` query.
* FILTER_SCRIPT: Allows to run scripts in a filter script context.
This context is used in the `script` query.
In both contexts a index name needs to be specified and a sample document.
The document is needed to create an in-memory index that the script can
access via the `doc[...]` and other notations. The index name is needed
because a mapping is needed to index the document.
Examples:
```
POST /_scripts/painless/_execute
{
"script": {
"source": "doc['field'].value.length()"
},
"context" : {
"search_script": {
"document": {
"field": "four"
},
"index": "my-index"
}
}
}
```
Returns:
```
{
"result": 4
}
```
POST /_scripts/painless/_execute
{
"script": {
"source": "doc['field'].value.length() <= params.max_length",
"params": {
"max_length": 4
}
},
"context" : {
"filter_script": {
"document": {
"field": "four"
},
"index": "my-index"
}
}
}
Returns:
```
{
"result": true
}
```
Also changed PainlessExecuteAction.TransportAction to use TransportSingleShardAction
instead of HandledAction, because now in case score or filter contexts are used
the request needs to be redirected to a node that has an active IndexService
for the index being referenced (a node with a shard copy for that index).
177 lines
4.3 KiB
Plaintext
177 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 compatable with the document being indexed.
|
|
|
|
====== Example
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------
|
|
PUT /my-index
|
|
{
|
|
"mappings": {
|
|
"_doc": {
|
|
"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 compatable 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": {
|
|
"_doc": {
|
|
"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
|