opensearch-docs-cn/_api-reference/script-apis/create-stored-script.md

layout	title	parent	nav_order
default	Create or Update Stored Script	Script APIs	1

Create or update stored script

Introduced 1.0 {: .label .label-purple }

Creates or updates a stored script or search template.

For additional information about Painless scripting, see:

• k-NN Painless Scripting extensions.

• k-NN.

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 request body. Search templates also support Mustache variables.

Example request

The sample uses an index called books with the following documents:

{"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.

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.html %}

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:

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        "
  }
}'

{% 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:

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 for information about running the script.

Example response

The PUT _scripts/my-first-script request returns the following field:

{
  "acknowledged" : true
}

To determine whether the script was successfully created, use the 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.

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:

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:

{
  "acknowledged" : true
}