112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
---
|
|
layout: default
|
|
title: Create or Update Stored Script
|
|
parent: Script APIs
|
|
nav_order: 1
|
|
---
|
|
|
|
## Create or update stored script
|
|
|
|
Creates or updates a stored script or search template.
|
|
|
|
For additional 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/index/).
|
|
|
|
|
|
### 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]({{site.url}}{{site.baseurl}}/api-reference/search) API request body. Search templates also support Mustache variables. |
|
|
|
|
#### 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}}/api-reference/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}}/api-reference/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. | |