add instruction for using parameters and sorting for stored script (#1834)
* add instruction for using parameters in stored script and sorting example results using stored script Signed-off-by: syrinx05p <4161768+syrinx05p@users.noreply.github.com> * Apply suggestions from tech writer review * Apply suggestions from doc review * Apply suggestions from editorial review Co-authored-by: Nathan Bower <nbower@amazon.com> * Apply suggestions from editorial review --------- Signed-off-by: syrinx05p <4161768+syrinx05p@users.noreply.github.com> Co-authored-by: syrinx05p <4161768+syrinx05p@users.noreply.github.com> Co-authored-by: Aria Marble <111301581+ariamarble@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
This commit is contained in:
tkykenmt
GitHub
parent
f154992ccd
commit
7539e7fb44
|
|
@ -93,6 +93,26 @@ curl -XPUT "http://opensearch:9200/_scripts/my-first-script" -H 'Content-Type: a
|
|||
````
|
||||
{% include copy.html %}
|
||||
|
||||
|
||||
The following request creates the Painless script `my-first-script`, which sums the ratings for each book and displays the sum in the output:
|
||||
|
||||
````json
|
||||
PUT _scripts/my-first-script
|
||||
{
|
||||
"script": {
|
||||
"lang": "painless",
|
||||
"source": """
|
||||
int total = 0;
|
||||
for (int i = 0; i < doc['ratings'].length; ++i) {
|
||||
total += doc['ratings'][i];
|
||||
}
|
||||
return total;
|
||||
"""
|
||||
}
|
||||
}
|
||||
````
|
||||
{% include copy-curl.html %}
|
||||
|
||||
See [Execute Painless stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/exec-stored-script/) for information about running the script.
|
||||
|
||||
#### Example response
|
||||
|
|
@ -112,4 +132,39 @@ To determine whether the script was successfully created, use the [Get stored sc
|
|||
|
||||
| Field | Data type | Description |
|
||||
:--- | :--- | :---
|
||||
| acknowledged | Boolean | whether the request was received. |
|
||||
| acknowledged | Boolean | Whether the request was received. |
|
||||
|
||||
## Creating or updating a stored script with parameters
|
||||
|
||||
The Painless script supports `params` to pass variables to the script.
|
||||
|
||||
### Example
|
||||
|
||||
The following request creates the Painless script `multiplier-script`. The request sums the ratings for each book, multiplies the summed value by the `multiplier` parameter, and displays the result in the output:
|
||||
|
||||
````json
|
||||
PUT _scripts/multiplier-script
|
||||
{
|
||||
"script": {
|
||||
"lang": "painless",
|
||||
"source": """
|
||||
int total = 0;
|
||||
for (int i = 0; i < doc['ratings'].length; ++i) {
|
||||
total += doc['ratings'][i];
|
||||
}
|
||||
return total * params['multiplier'];
|
||||
"""
|
||||
}
|
||||
}
|
||||
````
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Example response
|
||||
|
||||
The `PUT _scripts/multiplier-script` request returns the following field:
|
||||
|
||||
````json
|
||||
{
|
||||
"acknowledged" : true
|
||||
}
|
||||
````
|
||||
|
|
@ -127,3 +127,197 @@ The `GET books/_search` request returns the following fields:
|
|||
| _id | String | Document ID. |
|
||||
| _score | Float | Document's relevance score. |
|
||||
| fields | Object | Fields and their value returned from the script. |
|
||||
|
||||
## Running a Painless stored script with parameters
|
||||
|
||||
To pass different parameters to the script each time when running a query, define `params` in `script_fields`.
|
||||
|
||||
### Example
|
||||
|
||||
The following request runs the stored script that was created in [Create or update stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/create-stored-script/). The script sums the ratings for each book, multiplies the summed value by the `multiplier` parameter, and displays the result in the output.
|
||||
|
||||
* The script's target is the `books` index.
|
||||
|
||||
* The `"match_all": {}` property value is an empty object, indicating that it processes each document in the index.
|
||||
|
||||
* The `total_ratings` field value is the result of the `multiplier-script` execution. See [Creating or updating a stored script with parameters]({{site.url}}{{site.baseurl}}/api-reference/script-apis/create-stored-script/).
|
||||
|
||||
* `"multiplier": 2` in the `params` field is a variable passed to the stored script `multiplier-script`:
|
||||
|
||||
````json
|
||||
GET books/_search
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"script_fields": {
|
||||
"total_ratings": {
|
||||
"script": {
|
||||
"id": "multiplier-script",
|
||||
"params": {
|
||||
"multiplier": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Example response
|
||||
````json
|
||||
{
|
||||
"took" : 12,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 3,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : 1.0,
|
||||
"fields" : {
|
||||
"total_ratings" : [
|
||||
16
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : 1.0,
|
||||
"fields" : {
|
||||
"total_ratings" : [
|
||||
30
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : 1.0,
|
||||
"fields" : {
|
||||
"total_ratings" : [
|
||||
24
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sort results using painless stored script
|
||||
You can use painless stored script to sort results.
|
||||
|
||||
### Sample request
|
||||
|
||||
````json
|
||||
GET books/_search
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"script_fields": {
|
||||
"total_ratings": {
|
||||
"script": {
|
||||
"id": "multiplier-script",
|
||||
"params": {
|
||||
"multiplier": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"sort": {
|
||||
"_script": {
|
||||
"type": "number",
|
||||
"script": {
|
||||
"id": "multiplier-script",
|
||||
"params": {
|
||||
"multiplier": 2
|
||||
}
|
||||
},
|
||||
"order": "desc"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
````json
|
||||
{
|
||||
"took" : 90,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 5,
|
||||
"successful" : 5,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 3,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : null,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "2",
|
||||
"_score" : null,
|
||||
"fields" : {
|
||||
"total_ratings" : [
|
||||
30
|
||||
]
|
||||
},
|
||||
"sort" : [
|
||||
30.0
|
||||
]
|
||||
},
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "1",
|
||||
"_score" : null,
|
||||
"fields" : {
|
||||
"total_ratings" : [
|
||||
24
|
||||
]
|
||||
},
|
||||
"sort" : [
|
||||
24.0
|
||||
]
|
||||
},
|
||||
{
|
||||
"_index" : "books",
|
||||
"_type" : "_doc",
|
||||
"_id" : "3",
|
||||
"_score" : null,
|
||||
"fields" : {
|
||||
"total_ratings" : [
|
||||
16
|
||||
]
|
||||
},
|
||||
"sort" : [
|
||||
16.0
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue