mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-08 14:05:27 +00:00
d5ad86dad9
Previously we only turned on tests if we saw either `// CONSOLE` or
`// TEST`. These magic comments are difficult for the docs build to deal
with so it has moved away from using them where possible. We should
catch up. This adds another trigger to enable testing: marking a snippet
with the `console` language. It looks like this:
```
[source,console]
----
GET /
----
```
This saves a line which is nice, I guess. But it is more important to me
that this is consistent with the way the docs build works now.
Similarly this enables response testing when you mark a snippet with the
language `console-result`. That looks like:
```
[source,console-result]
----
{
"result": "0.1"
}
----
```
`// TESTRESPONSE` is still available for situations like `// TEST`: when
the response isn't *in* the console-result language (like `_cat`) or
when you want to perform substitutions on the generated test.
Should unblock #46159.
167 lines
4.2 KiB
Plaintext
167 lines
4.2 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,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 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,console]
|
|
----------------------------------------------------------------
|
|
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"
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------
|
|
|
|
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 specified that will be used to compute a score.
|
|
|
|
*Example*
|
|
|
|
[source,console]
|
|
----------------------------------------------------------------
|
|
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
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------
|
|
|
|
Response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"result": 0.8
|
|
}
|
|
--------------------------------------------------
|