From 21386b05d0e8ecc0d8a6b173e370d6906db657ad Mon Sep 17 00:00:00 2001 From: Aria Marble <111301581+ariamarble@users.noreply.github.com> Date: Fri, 2 Sep 2022 15:09:13 -0700 Subject: [PATCH] script api documentation (#1094) * Add script documentation. Signed-off-by: Steve Murphy * Use my own example script insteady of Elastic's. Signed-off-by: Steve Murphy * edditing and format changes. verified API requests and scripts. various corrections Signed-off-by: ariamarble * made a couple of suggested changes Signed-off-by: ariamarble * made further corrections Signed-off-by: ariamarble Signed-off-by: Steve Murphy Signed-off-by: ariamarble Co-authored-by: Steve Murphy --- .../_script-apis/create-stored-script.md | 114 ++++ .../rest-api/_script-apis/delete-script.md | 54 ++ .../_script-apis/exec-stored-script.md | 129 ++++ .../_script-apis/get-script-contexts.md | 576 ++++++++++++++++++ .../_script-apis/get-stored-script.md | 69 +++ _opensearch/rest-api/_script-apis/index.md | 21 + 6 files changed, 963 insertions(+) create mode 100644 _opensearch/rest-api/_script-apis/create-stored-script.md create mode 100644 _opensearch/rest-api/_script-apis/delete-script.md create mode 100644 _opensearch/rest-api/_script-apis/exec-stored-script.md create mode 100644 _opensearch/rest-api/_script-apis/get-script-contexts.md create mode 100644 _opensearch/rest-api/_script-apis/get-stored-script.md create mode 100644 _opensearch/rest-api/_script-apis/index.md diff --git a/_opensearch/rest-api/_script-apis/create-stored-script.md b/_opensearch/rest-api/_script-apis/create-stored-script.md new file mode 100644 index 00000000..be3adf41 --- /dev/null +++ b/_opensearch/rest-api/_script-apis/create-stored-script.md @@ -0,0 +1,114 @@ +--- +layout: default +title: Create or Update Stored Script +parent: Script APIs +grand_parent: REST API reference +nav_order: 1 +--- + +## Create or update stored script + +Creates or updates a stored script or search template. + +For additonal information about Painless scripting, see: + +* [k-NN Painless Scripting extensions]({{site.url}}{{site.baseurl}}/search-plugins/knn/painless-functions/). + +* [k-NN]({{site.url}}{{site.baseurl}}/search-plugins/knn/inswz/). + + +### Path parameters + +| Parameter | Data Type | Description | +:--- | :--- | :--- +| script-id | String | Stored script or search template ID. Must be unique across the cluster. Required. | + +### Query parameters + +All parameters are optional. + +| Parameter | Data Type | Description | +:--- | :--- | :--- +| context | String | Context in which the script or search template is to run. To prevent errors, the API immediately compiles the script or template in this context. | +| cluster_manager_timeout | Time | Amount of time to wait for a connection to the cluster manager. Defaults to 30 seconds. | +| timeout | Time | The period of time to wait for a response. If a response is not received before the timeout value, the request fails and returns an error. Defaults to 30 seconds.| + +### Request fields + +| Field | Data Type | Description | +:--- | :--- | :--- +| script | Object | Defines the script or search template, its parameters, and its language. See *Script object* below. | + +*Script object* + +| Field | Data Type | Description | +:--- | :--- | :--- +| lang | String | Scripting language. Required. | +| source | String or Object | Required.

For scripts, a string with the contents of the script.

For search templates, an object that defines the search template. Supports the same parameters as the [Search API]({{site.url}}{{site.baseurl}}/opensearch/rest-api/search)'s request body. Search templates also support Mustache variables. | +| params | Object | The script's or search template's parameters. | + +#### Sample request + +The sample uses an index called `books` with the following documents: + +````json +{"index":{"_id":1}} +{"name":"book1","author":"Faustine","ratings":[4,3,5]} +{"index":{"_id":2}} +{"name":"book2","author":"Amit","ratings":[5,5,5]} +{"index":{"_id":3}} +{"name":"book3","author":"Gilroy","ratings":[2,1,5]} +```` + +The following request creates the Painless script `my-first-script`. It 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; + """ + } +} +```` +The example above uses the syntax of the Dev Tools console in OpenSearch Dashboards. You can also use a curl request. +{: .note } + +The following curl request is equivalent to the previous Dashboards console example: + +````json +curl -XPUT "http://opensearch:9200/_scripts/my-first-script" -H 'Content-Type: application/json' -d' +{ + "script": { + "lang": "painless", + "source": "\n int total = 0;\n for (int i = 0; i < doc['\''ratings'\''].length; ++i) {\n total += doc['\''ratings'\''][i];\n }\n return total;\n " + } +}' +```` + +See [Execute Painless stored script]({{site.url}}{{site.baseurl}}/opensearch/rest-api/_script-apis/exec-stored-script) for information about running the script. + +#### Sample response + +The `PUT _scripts/my-first-script` request returns the following field: + +````json +{ + "acknowledged" : true +} +```` + +To determine whether the script was successfully created, use the [Get stored script]({{site.url}}{{site.baseurl}}/opensearch/rest-api/_script-apis/get-stored-script/) API, passing the script name as the `script` path parameter. +{: .note} + +### Response fields + +| Field | Data Type | Description | +:--- | :--- | :--- +| acknowledged | Boolean | whether the request was received. | \ No newline at end of file diff --git a/_opensearch/rest-api/_script-apis/delete-script.md b/_opensearch/rest-api/_script-apis/delete-script.md new file mode 100644 index 00000000..239efd2e --- /dev/null +++ b/_opensearch/rest-api/_script-apis/delete-script.md @@ -0,0 +1,54 @@ +--- +layout: default +title: Delete Script +parent: Script APIs +grand_parent: REST API reference +nav_order: 4 +--- + +## Delete script + +Deletes a stored script + +### Path parameters + +Path parameters are optional. + +| Parameter | Data Type | Description | +:--- | :--- | :--- +| script-id | String | ID of script to delete. | + +### Query parameters + +| Parameter | Data Type | Description | +:--- | :--- | :--- +| cluster_manager_timeout | Time | Amount of time to wait for a connection to the cluster manager. Optional, defaults to `30s`. | +| timeout | Time | The period of time to wait for a response. If a response is not received before the timeout value, the request will be dropped. + +#### Sample request + +The following request deletes the `my-first-script` script: + +````json +DELETE _scripts/my-script +```` + +#### Sample response + +The `DELETE _scripts/my-first-script` request returns the following field: + +````json +{ + "acknowledged" : true +} +```` + +To determine whether the stored script was successfully deleted, use the [Get stored script]({{site.url}}{{site.baseurl}}/opensearch/rest-api/_script-apis/get-stored-script/) API, passing the script name as the `script` path parameter. + +### Response fields + +The request returns the following response fields: + +| Field | Data Type | Description | +:--- | :--- | :--- +| acknowledged | Boolean | Whether the delete script request was received. | \ No newline at end of file diff --git a/_opensearch/rest-api/_script-apis/exec-stored-script.md b/_opensearch/rest-api/_script-apis/exec-stored-script.md new file mode 100644 index 00000000..21b8f1af --- /dev/null +++ b/_opensearch/rest-api/_script-apis/exec-stored-script.md @@ -0,0 +1,129 @@ +--- +layout: default +title: Execute Painless Stored Script +parent: Script APIs +grand_parent: REST API reference +nav_order: 2 +--- + +## Execute Painless stored script + +Runs a stored script written in the Painless language. + +OpenSearch provides several ways to run a script; the following sections show how to run a script by passing script information in the request body of a `GET /_search` request. + +### Request fields + +| Field | Data Type | Description | +:--- | :--- | :--- +| query | Object | A filter that specifies documents to process. | +| script_fields | Object | Fields to include in output. | +| script | Object | ID of the script that produces a value for a field. | + +#### Sample request + +The following request runs the stored script that was created in [Create or Update Stored Script]({{site.url}}{{site.baseurl}}/opensearch/rest-api/_script-apis/create-stored-script/). The script sums the ratings for each book and displays the sum in the `total_ratings` field in the output. + +* The script's target is the `books` index. + +* The `"match_all": {}` property value is an empty object indicating to process each document in the index. + +* The `total_ratings` field value is the result of the `my-first-script` execution. (See [Create or Update Stored Script]({{site.url}}{{site.baseurl}}/opensearch/rest-api/_script-apis/create-stored-script/).) + +````json +GET books/_search +{ + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "my-first-script" + } + } + } +} +```` + +#### Sample response + +The `GET books/_search` request returns the following fields: + +````json +{ + "took" : 2, + "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", + "_id" : "1", + "_score" : 1.0, + "fields" : { + "total_ratings" : [ + 12 + ] + } + }, + { + "_index" : "books", + "_id" : "2", + "_score" : 1.0, + "fields" : { + "total_ratings" : [ + 15 + ] + } + }, + { + "_index" : "books", + "_id" : "3", + "_score" : 1.0, + "fields" : { + "total_ratings" : [ + 8 + ] + } + } + ] + } +} +```` + +### Response fields + +| Field | Data Type | Description | +:--- | :--- | :--- +| took | Integer | How long the operation took in milliseconds. | +| timed_out | Boolean | Whether the operation timed out. | +| _shards | Object | Total number of shards processed and also the total number of successful, skipped, and not processed. | +| hits | Object | Contains high-level information about the documents processed and an array of `hits` objects. See [Hits object](#hits-object). | + +#### Hits object + +| Field | Data Type | Description | +:--- | :--- | :--- +| total | Object | Total number of documents processed and their relationship to the `match` request field. | +| max_score | Double | Highest relevance score returned from all the hits. | +| hits | Array | Information about each document that was processed. See [Document object](#Document-object). | + +#### Document object + +| Field | Data Type | Description | +:--- | :--- | :--- +| _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 diff --git a/_opensearch/rest-api/_script-apis/get-script-contexts.md b/_opensearch/rest-api/_script-apis/get-script-contexts.md new file mode 100644 index 00000000..650fb062 --- /dev/null +++ b/_opensearch/rest-api/_script-apis/get-script-contexts.md @@ -0,0 +1,576 @@ +--- +layout: default +title: Get Stored Script Contexts +parent: Script APIs +grand_parent: REST API reference +nav_order: 4 +--- + +## Get stored script contexts + +Retrieves all contexts for stored scripts. + +#### Sample request + +````json +GET _script_context +```` + +#### Sample response + +The `GET _script_context` request returns the following fields: + +````json +{ + "contexts" : [ + { + "name" : "aggregation_selector", + "methods" : [ + { + "name" : "execute", + "return_type" : "boolean", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "aggs", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Object", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "get_score", + "return_type" : "java.lang.Number", + "params" : [ ] + }, + { + "name" : "get_value", + "return_type" : "java.lang.Object", + "params" : [ ] + } + ] + }, + { + "name" : "aggs_combine", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Object", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getState", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "aggs_init", + "methods" : [ + { + "name" : "execute", + "return_type" : "void", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getState", + "return_type" : "java.lang.Object", + "params" : [ ] + } + ] + }, + { + "name" : "aggs_map", + "methods" : [ + { + "name" : "execute", + "return_type" : "void", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getState", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "get_score", + "return_type" : "double", + "params" : [ ] + } + ] + }, + { + "name" : "aggs_reduce", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Object", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getStates", + "return_type" : "java.util.List", + "params" : [ ] + } + ] + }, + { + "name" : "analysis", + "methods" : [ + { + "name" : "execute", + "return_type" : "boolean", + "params" : [ + { + "type" : "org.opensearch.analysis.common.AnalysisPredicateScript$Token", + "name" : "token" + } + ] + } + ] + }, + { + "name" : "bucket_aggregation", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Number", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "field", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Object", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "filter", + "methods" : [ + { + "name" : "execute", + "return_type" : "boolean", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "ingest", + "methods" : [ + { + "name" : "execute", + "return_type" : "void", + "params" : [ + { + "type" : "java.util.Map", + "name" : "ctx" + } + ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "interval", + "methods" : [ + { + "name" : "execute", + "return_type" : "boolean", + "params" : [ + { + "type" : "org.opensearch.index.query.IntervalFilterScript$Interval", + "name" : "interval" + } + ] + } + ] + }, + { + "name" : "moving-function", + "methods" : [ + { + "name" : "execute", + "return_type" : "double", + "params" : [ + { + "type" : "java.util.Map", + "name" : "params" + }, + { + "type" : "double[]", + "name" : "values" + } + ] + } + ] + }, + { + "name" : "number_sort", + "methods" : [ + { + "name" : "execute", + "return_type" : "double", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "get_score", + "return_type" : "double", + "params" : [ ] + } + ] + }, + { + "name" : "painless_test", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Object", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "processor_conditional", + "methods" : [ + { + "name" : "execute", + "return_type" : "boolean", + "params" : [ + { + "type" : "java.util.Map", + "name" : "ctx" + } + ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "score", + "methods" : [ + { + "name" : "execute", + "return_type" : "double", + "params" : [ + { + "type" : "org.opensearch.script.ScoreScript$ExplanationHolder", + "name" : "explanation" + } + ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "get_score", + "return_type" : "double", + "params" : [ ] + } + ] + }, + { + "name" : "script_heuristic", + "methods" : [ + { + "name" : "execute", + "return_type" : "double", + "params" : [ + { + "type" : "java.util.Map", + "name" : "params" + } + ] + } + ] + }, + { + "name" : "similarity", + "methods" : [ + { + "name" : "execute", + "return_type" : "double", + "params" : [ + { + "type" : "double", + "name" : "weight" + }, + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Query", + "name" : "query" + }, + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Field", + "name" : "field" + }, + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Term", + "name" : "term" + }, + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Doc", + "name" : "doc" + } + ] + } + ] + }, + { + "name" : "similarity_weight", + "methods" : [ + { + "name" : "execute", + "return_type" : "double", + "params" : [ + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Query", + "name" : "query" + }, + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Field", + "name" : "field" + }, + { + "type" : "org.opensearch.index.similarity.ScriptedSimilarity$Term", + "name" : "term" + } + ] + } + ] + }, + { + "name" : "string_sort", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.String", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "get_score", + "return_type" : "double", + "params" : [ ] + } + ] + }, + { + "name" : "template", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.String", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "terms_set", + "methods" : [ + { + "name" : "execute", + "return_type" : "java.lang.Number", + "params" : [ ] + }, + { + "name" : "getDoc", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "trigger", + "methods" : [ + { + "name" : "execute", + "return_type" : "boolean", + "params" : [ + { + "type" : "org.opensearch.alerting.script.QueryLevelTriggerExecutionContext", + "name" : "ctx" + } + ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + }, + { + "name" : "update", + "methods" : [ + { + "name" : "execute", + "return_type" : "void", + "params" : [ ] + }, + { + "name" : "getCtx", + "return_type" : "java.util.Map", + "params" : [ ] + }, + { + "name" : "getParams", + "return_type" : "java.util.Map", + "params" : [ ] + } + ] + } + ] +} +```` + +### Response fields + +The `GET _scripts/my-first-script` request returns the following response fields: + +| Field | Data Type | Description | +:--- | :--- | :--- +| contexts | List | A list of all contexts. See [Script object](#script-context). | + +#### Script context + +| Field | Data Type | Description | +:--- | :--- | :--- +| name | String | The context name. | +| methods | List | List of the context's allowable methods. See [Script object](#context-methods). | + +#### Context methods + +| Field | Data Type | Description | +:--- | :--- | :--- +| name | String | Method name. | +| name | String | Type that the method returns (`boolean`, `object`, `number`, and so on). | +| params | List | List of the parameters accepted by the method. See [Script object](#method-parameters). | + +#### Method parameters + +| Field | Data Type | Description | +:--- | :--- | :--- +| type | String | Parameter data type. | +| name | String | Parameter name. | \ No newline at end of file diff --git a/_opensearch/rest-api/_script-apis/get-stored-script.md b/_opensearch/rest-api/_script-apis/get-stored-script.md new file mode 100644 index 00000000..ef8322ea --- /dev/null +++ b/_opensearch/rest-api/_script-apis/get-stored-script.md @@ -0,0 +1,69 @@ +--- +layout: default +title: Get Stored Script +parent: Script APIs +grand_parent: REST API reference +nav_order: 3 +--- + +## Get stored script + +Retrieves a stored script. + +### Path parameters + +| Parameter | Data Type | Description | +:--- | :--- | :--- +| script | String | Stored script or search template name. Required.| + +### Query parameters + +| Parameter | Data Type | Description | +:--- | :--- | :--- +| cluster_manager_timeout | Time | Amount of time to wait for a connection to the cluster manager. Optional, defaults to `30s`. | + +#### Sample request + +The following retrieves the `my-first-script` stored script. + +````json +GET _scripts/my-first-script +```` + +#### Sample response + +The `GET _scripts/my-first-script` request returns the following fields: + +````json +{ + "_id" : "my-first-script", + "found" : true, + "script" : { + "lang" : "painless", + "source" : """ + int total = 0; + for (int i = 0; i < doc['ratings'].length; ++i) { + total += doc['ratings'][i]; + } + return total; + """ + } +} +```` + +### Response fields + +The `GET _scripts/my-first-script` request returns the following response fields: + +| Field | Data Type | Description | +:--- | :--- | :--- +| _id | String | The script's name. | +| found | Boolean | The requested script exists and was retrieved. | +| script | Object | The script definition. See [Script object](#script-object). | + +#### Script object + +| Field | Data Type | Description | +:--- | :--- | :--- +| lang | String | The script's language. | +| source | String | The script's body. | \ No newline at end of file diff --git a/_opensearch/rest-api/_script-apis/index.md b/_opensearch/rest-api/_script-apis/index.md new file mode 100644 index 00000000..21f092b8 --- /dev/null +++ b/_opensearch/rest-api/_script-apis/index.md @@ -0,0 +1,21 @@ +--- +layout: default +title: Script APIs +parent: REST API reference +has_children: true +nav_order: 160 +redirect_from: + - /opensearch/rest-api/script-apis/ +--- + +# Script APIs + +The script APIs allow you to work with stored scripts. Stored scripts are part of the cluster state and reduce compilation time and enhance search speed. The default scripting language is Painless. + +You perform the following operations on stored scripts: +* [create]({{site.url}}{{site.baseurl}}/opensearch/rest-api/script-apis/create-stored-script/) +* [update]({{site.url}}{{site.baseurl}}/opensearch/rest-api/script-apis/create-stored-script/) +* [execute]({{site.url}}{{site.baseurl}}/opensearch/rest-api/script-apis/exec-stored-script/) +* [retrieve]({{site.url}}{{site.baseurl}}/opensearch/rest-api/script-apis/get-stored-script/) +* [delete]({{site.url}}{{site.baseurl}}/opensearch/rest-api/script-apis/delete-script/) +* You can also retrieve stored [script contexts]({{site.url}}{{site.baseurl}}/opensearch/rest-api/script-apis/get-script-contexts/). \ No newline at end of file