script api documentation (#1094) (#1095)

* Add script documentation. Signed-off-by: Steve Murphy <[email protected]> * Use my own example script insteady of Elastic's. Signed-off-by: Steve Murphy <[email protected]> * edditing and format changes. verified API requests and scripts. various corrections Signed-off-by: ariamarble <[email protected]> * made a couple of suggested changes Signed-off-by: ariamarble <[email protected]> * made further corrections Signed-off-by: ariamarble <[email protected]> Signed-off-by: Steve Murphy <[email protected]> Signed-off-by: ariamarble <[email protected]> Co-authored-by: Steve Murphy <[email protected]> (cherry picked from commit 21386b0) Co-authored-by: Aria Marble <[email protected]>
opensearch-project · Sep 6, 2022 · 49825b2 · 49825b2
1 parent dea8441
commit 49825b2
Show file tree

Hide file tree

Showing 6 changed files with 963 additions and 0 deletions.
diff --git a/_opensearch/rest-api/_script-apis/create-stored-script.md 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. <br />  <br /> For scripts, a string with the contents of the script. <br />  <br /> 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. |
diff --git a/_opensearch/rest-api/_script-apis/delete-script.md 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 <HTTP METHOD> <endpoint> request returns the following response fields:
+
+| Field | Data Type | Description | 
+:--- | :--- | :---
+| acknowledged | Boolean | Whether the delete script request was received. |
diff --git a/_opensearch/rest-api/_script-apis/exec-stored-script.md 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 <index>/_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. |