From 7539e7fb44e87ab9587d7df73b2fd178618692f8 Mon Sep 17 00:00:00 2001 From: tkykenmt <4161768+tkykenmt@users.noreply.github.com> Date: Fri, 10 Mar 2023 05:45:15 +0900 Subject: [PATCH] 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 * 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 --- .../script-apis/create-stored-script.md | 57 ++++- .../script-apis/exec-stored-script.md | 196 +++++++++++++++++- 2 files changed, 251 insertions(+), 2 deletions(-) diff --git a/_api-reference/script-apis/create-stored-script.md b/_api-reference/script-apis/create-stored-script.md index e782be23..68239821 100644 --- a/_api-reference/script-apis/create-stored-script.md +++ b/_api-reference/script-apis/create-stored-script.md @@ -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. | \ No newline at end of file +| 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 +} +```` \ No newline at end of file diff --git a/_api-reference/script-apis/exec-stored-script.md b/_api-reference/script-apis/exec-stored-script.md index 8fcaf8a3..fccb325c 100644 --- a/_api-reference/script-apis/exec-stored-script.md +++ b/_api-reference/script-apis/exec-stored-script.md @@ -126,4 +126,198 @@ The `GET books/_search` request returns the following fields: | _index | String | Index that contains the document. | | _id | String | Document ID. | | _score | Float | Document's relevance score. | -| fields | Object | Fields and their value returned from the script. | \ No newline at end of file +| 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 + ] + } + ] + } +} +``` \ No newline at end of file