How to use scripts
editHow to use scripts
editWherever scripting is supported in the Elasticsearch API, the syntax follows the same pattern:
The language the script is written in, which defaults to |
|
The script itself which may be specified as |
|
Any named parameters that should be passed into the script. |
For example, the following script is used in a search request to return a scripted field:
PUT my_index/_doc/1 { "my_field": 5 } GET my_index/_search { "script_fields": { "my_doubled_field": { "script": { "lang": "expression", "source": "doc['my_field'] * multiplier", "params": { "multiplier": 2 } } } } }
Script Parameters
edit-
lang
-
Specifies the language the script is written in. Defaults to
painless
. -
source
,id
-
Specifies the source of the script. An
inline
script is specifiedsource
as in the example above. Astored
script is specifiedid
and is retrieved from the cluster state (see Stored Scripts). -
params
- Specifies any named parameters that are passed into the script as variables.
Prefer parameters
The first time Elasticsearch sees a new script, it compiles it and stores the compiled version in a cache. Compilation can be a heavy process.
If you need to pass variables into the script, you should pass them in as
named params
instead of hard-coding values into the script itself. For
example, if you want to be able to multiply a field value by different
multipliers, don’t hard-code the multiplier into the script:
"source": "doc['my_field'] * 2"
Instead, pass it in as a named parameter:
"source": "doc['my_field'] * multiplier", "params": { "multiplier": 2 }
The first version has to be recompiled every time the multiplier changes. The second version is only compiled once.
If you compile too many unique scripts within a small amount of time,
Elasticsearch will reject the new dynamic scripts with a
circuit_breaking_exception
error. By default, up to 15 inline scripts per
minute will be compiled. You can change this setting dynamically by setting
script.max_compilations_rate
.
Short Script Form
editA short script form can be used for brevity. In the short form, script
is represented
by a string instead of an object. This string contains the source of the script.
Short form:
"script": "ctx._source.likes++"
The same script in the normal form:
"script": { "source": "ctx._source.likes++" }
Stored Scripts
editScripts may be stored in and retrieved from the cluster state using the
_scripts
end-point.
Request Examples
editThe following are examples of using a stored script that lives at
/_scripts/{id}
.
First, create the script called calculate-score
in the cluster state:
POST _scripts/calculate-score { "script": { "lang": "painless", "source": "Math.log(_score * 2) + params.my_modifier" } }
This same script can be retrieved with:
GET _scripts/calculate-score
Stored scripts can be used by specifying the id
parameters as follows:
GET _search { "query": { "script": { "script": { "id": "calculate-score", "params": { "my_modifier": 2 } } } } }
And deleted with:
DELETE _scripts/calculate-score
Script Caching
editAll scripts are cached by default so that they only need to be recompiled
when updates occur. By default, scripts do not have a time-based expiration, but
you can change this behavior by using the script.cache.expire
setting.
You can configure the size of this cache by using the script.cache.max_size
setting.
By default, the cache size is 100
.
The size of scripts is limited to 65,535 bytes. This can be
changed by setting script.max_size_in_bytes
setting to increase that soft
limit, but if scripts are really large then a
native script engine should be considered.