Execute Painless stored script

Introduced 1.0

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.

Path and HTTP methods

  1. GET books/_search
  2. {
  3.   "script_fields": {
  4.     "total_ratings": {
  5.       "script": {
  6.         "id": "my-first-script" 
  7.       }
  8.     }
  9.   }
  10. }

Request field options

FieldData typeDescription
queryObjectA filter that specifies documents to process.
script_fieldsObjectFields to include in output.
scriptObjectID of the script that produces a value for a field.

Example request

The following request runs the stored script that was created in Create or update 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.

  1. GET books/_search
  2. {
  3.    "query": {
  4.     "match_all": {}
  5.   },
  6.   "script_fields": {
  7.     "total_ratings": {
  8.       "script": {
  9.         "id": "my-first-script" 
  10.       }
  11.     }
  12.   }
  13. }

copy

Example response

The GET books/_search request returns the following fields:

  1. {
  2.   "took" : 2,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 3,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "books",
  19.         "_id" : "1",
  20.         "_score" : 1.0,
  21.         "fields" : {
  22.           "total_ratings" : [
  23.             12
  24.           ]
  25.         }
  26.       },
  27.       {
  28.         "_index" : "books",
  29.         "_id" : "2",
  30.         "_score" : 1.0,
  31.         "fields" : {
  32.           "total_ratings" : [
  33.             15
  34.           ]
  35.         }
  36.       },
  37.       {
  38.         "_index" : "books",
  39.         "_id" : "3",
  40.         "_score" : 1.0,
  41.         "fields" : {
  42.           "total_ratings" : [
  43.             8
  44.           ]
  45.         }
  46.       }
  47.     ]
  48.   }
  49. }

Response body fields

FieldData typeDescription
tookIntegerHow long the operation took in milliseconds.
timed_outBooleanWhether the operation timed out.
_shardsObjectTotal number of shards processed and also the total number of successful, skipped, and not processed.
hitsObjectContains high-level information about the documents processed and an array of hits objects. See Hits object.

Hits object

FieldData typeDescription
totalObjectTotal number of documents processed and their relationship to the match request field.
max_scoreDoubleHighest relevance score returned from all the hits.
hitsArrayInformation about each document that was processed. See Document object.

Document object

FieldData typeDescription
_indexStringIndex that contains the document.
_idStringDocument ID.
_scoreFloatDocument’s relevance score.
fieldsObjectFields 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. 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.

  • "multiplier": 2 in the params field is a variable passed to the stored script multiplier-script:

  1. GET books/_search
  2. {
  3.    "query": {
  4.     "match_all": {}
  5.   },
  6.   "script_fields": {
  7.     "total_ratings": {
  8.       "script": {
  9.         "id": "multiplier-script", 
  10.         "params": {
  11.           "multiplier": 2
  12.         }        
  13.       }
  14.     }
  15.   }
  16. }

copy

Example response

  1. {
  2.   "took" : 12,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 3,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "books",
  19.         "_type" : "_doc",
  20.         "_id" : "3",
  21.         "_score" : 1.0,
  22.         "fields" : {
  23.           "total_ratings" : [
  24.             16
  25.           ]
  26.         }
  27.       },
  28.       {
  29.         "_index" : "books",
  30.         "_type" : "_doc",
  31.         "_id" : "2",
  32.         "_score" : 1.0,
  33.         "fields" : {
  34.           "total_ratings" : [
  35.             30
  36.           ]
  37.         }
  38.       },
  39.       {
  40.         "_index" : "books",
  41.         "_type" : "_doc",
  42.         "_id" : "1",
  43.         "_score" : 1.0,
  44.         "fields" : {
  45.           "total_ratings" : [
  46.             24
  47.           ]
  48.         }
  49.       }
  50.     ]
  51.   }
  52. }

Sort results using painless stored script You can use painless stored script to sort results.

Sample request

  1. GET books/_search
  2. {
  3.    "query": {
  4.     "match_all": {}
  5.   },
  6.   "script_fields": {
  7.     "total_ratings": {
  8.       "script": {
  9.         "id": "multiplier-script",
  10.         "params": {
  11.           "multiplier": 2
  12.         }
  13.       }
  14.     }
  15.   },
  16.   "sort": {
  17.     "_script": {
  18.        "type": "number",
  19.        "script": {
  20.          "id": "multiplier-script",
  21.          "params": {
  22.            "multiplier": 2
  23.           }
  24.        },
  25.        "order": "desc"
  26.     }
  27.   }
  28. }

Sample response

  1. {
  2.   "took" : 90,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 5,
  6.     "successful" : 5,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 3,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : null,
  16.     "hits" : [
  17.       {
  18.         "_index" : "books",
  19.         "_type" : "_doc",
  20.         "_id" : "2",
  21.         "_score" : null,
  22.         "fields" : {
  23.           "total_ratings" : [
  24.             30
  25.           ]
  26.         },
  27.         "sort" : [
  28.           30.0
  29.         ]
  30.       },
  31.       {
  32.         "_index" : "books",
  33.         "_type" : "_doc",
  34.         "_id" : "1",
  35.         "_score" : null,
  36.         "fields" : {
  37.           "total_ratings" : [
  38.             24
  39.           ]
  40.         },
  41.         "sort" : [
  42.           24.0
  43.         ]
  44.       },
  45.       {
  46.         "_index" : "books",
  47.         "_type" : "_doc",
  48.         "_id" : "3",
  49.         "_score" : null,
  50.         "fields" : {
  51.           "total_ratings" : [
  52.             16
  53.           ]
  54.         },
  55.         "sort" : [
  56.           16.0
  57.         ]
  58.       }
  59.     ]
  60.   }
  61. }