Scripting

The scripting module allows to use scripts in order to evaluate custom expressions. For example, scripts can be used to return "script fields" as part of a search request, or can be used to evaluate a custom score for a query and so on.

The scripting module uses by default mvel as the scripting language with some extensions. mvel is used since it is extremely fast and very simple to use, and in most cases, simple expressions are needed (for example, mathematical equations).

script.groovy.sandbox.enabled: false

GET /_search
{
    "script_fields": {
        "my_field": {
            "script": "1 + my_var",
            "params": {
              "my_var": 2
            }
        }
    }
}

1 + my_var

GET /_search
{
    "script_fields": {
        "my_field": {
            "file": "my_test",
            "params": {
              "my_var": 2
            }
        }
    }
}

Additional lang plugins are provided to allow to execute scripts in different languages. Currently supported plugins are lang-javascript for JavaScript, lang-groovy for Groovy, and lang-python for Python. All places where a script parameter can be used, a lang parameter (on the same level) can be provided to define the language of the script. The lang options are mvel, js, groovy, python, expression, and native.

To increase security, Elasticsearch does not allow you to specify scripts with a request. Instead, scripts must be placed in the scripts directory inside the configuration directory (the directory where elasticsearch.yml is). Scripts placed into this directory will automatically be picked up and be available to be used. Once a script has been placed in this directory, it can be referenced by name. For example, a script called calculate-score.mvel can be referenced in a request like this:

$ tree config
config
├── elasticsearch.yml
├── logging.yml
└── scripts
    └── calculate-score.mvel

$ cat config/scripts/calculate-score.mvel
Math.log(_score * 2) + my_modifier

curl -XPOST localhost:9200/_search -d '{
  "query": {
    "function_score": {
      "query": {
        "match": {
          "body": "foo"
        }
      },
      "functions": [
        {
          "script_score": {
            "script": "calculate-score",
            "params": {
              "my_modifier": 8
            }
          }
        }
      ]
    }
  }
}'

The name of the script is derived from the hierarchy of directories it exists under, and the file name without the lang extension. For example, a script placed under config/scripts/group1/group2/test.py will be named group1_group2_test.

The default scripting language (assuming no lang parameter is provided) is mvel. In order to change it set the script.default_lang to the appropriate language.

If dynamic scripting is enabled, Elasticsearch allows you to store scripts in an internal index known as .scripts and reference them by id. There are REST endpoints to manage indexed scripts as follows:

Requests to the scripts endpoint look like :

/_scripts/{lang}/{id}

Where the lang part is the language the script is in and the id part is the id of the script. In the .scripts index the type of the document will be set to the lang.

curl -XPOST localhost:9200/_scripts/mvel/indexedCalculateScore -d '{
     "script": "log(_score * 2) + my_modifier"
}'

This will create a document with id: indexedCalculateScore and type: mvel in the .scripts index. The type of the document is the language used by the script.

This script can be accessed at query time by appending _id to the script parameter and passing the script id. So script becomes script_id.:

curl -XPOST localhost:9200/_search -d '{
  "query": {
    "function_score": {
      "query": {
        "match": {
          "body": "foo"
        }
      },
      "functions": [
        {
          "script_score": {
            "script_id": "indexedCalculateScore",
            "params": {
              "my_modifier": 8
            }
          }
        }
      ]
    }
  }
}'

Note that you must have dynamic scripting enabled to use indexed scripts at query time.

The script can be viewed by:

curl -XGET localhost:9200/_scripts/mvel/calculate-score

This is rendered as:

'{
     "script": "log(_score * 2) + my_modifier"
}'

Indexed scripts can be deleted by:

curl -XDELETE localhost:9200/_scripts/mvel/calculate-score

We recommend running Elasticsearch behind an application or proxy, which protects Elasticsearch from the outside world. If users are allowed to run dynamic scripts (even in a search request), then they have the same access to your box as the user that Elasticsearch is running as. For this reason dynamic scripting is disabled by default.

First, you should not run Elasticsearch as the root user, as this would allow a script to access or do anything on your server, without limitations. Second, you should not expose Elasticsearch directly to users, but instead have a proxy application inbetween. If you do intend to expose Elasticsearch directly to your users, then you have to decide whether you trust them enough to run scripts on your box or not. If you do, you can enable dynamic scripting by adding the following setting to the config/elasticsearch.yml file on every node:

script.disable_dynamic: false

While this still allows execution of named scripts provided in the config, or native Java scripts registered through plugins, it also allows users to run arbitrary scripts via the API. Instead of sending the name of the file as the script, the body of the script can be sent instead.

There are three possible configuration values for the script.disable_dynamic setting, the default value is sandbox:

Elasticsearch sandboxes Groovy scripts that are compiled and executed in order to ensure they don’t perform unwanted actions. There are a number of options that can be used for configuring this sandbox:

When specifying whitelist or blacklist settings for the groovy sandbox, all options replace the current whitelist, they are not additive.

The config/scripts directory is scanned periodically for changes. New and changed scripts are reloaded and deleted script are removed from preloaded scripts cache. The reload frequency can be specified using watcher.interval setting, which defaults to 60s. To disable script reloading completely set script.auto_reload_enabled to false.

Even though mvel is pretty fast, this allows to register native Java based scripts for faster execution.

In order to allow for scripts, the NativeScriptFactory needs to be implemented that constructs the script that will be executed. There are two main types, one that extends AbstractExecutableScript and one that extends AbstractSearchScript (probably the one most users will extend, with additional helper classes in AbstractLongSearchScript, AbstractDoubleSearchScript, and AbstractFloatSearchScript).

Registering them can either be done by settings, for example: script.native.my.type set to sample.MyNativeScriptFactory will register a script named my. Another option is in a plugin, access ScriptModule and call registerScript on it.

Executing the script is done by specifying the lang as native, and the name of the script as the script.

Note, the scripts need to be in the classpath of elasticsearch. One simple way to do it is to create a directory under plugins (choose a descriptive name), and place the jar / classes files there. They will be automatically loaded.

Lucene’s expressions module provides a mechanism to compile a javascript expression to bytecode. This allows very fast execution, as if you had written a native script. Expression scripts can be used in script_score, script_fields, sort scripts and numeric aggregation scripts.

See the expressions module documentation for details on what operators and functions are available.

Variables in expression scripts are available to access:

There are a few limitations relative to other script languages:

In all scripts that can be used in facets, the current document’s score is accessible in doc.score. When using a script_score, the current score is available in _score.

see advanced scripting documentation

Most scripting revolve around the use of specific document fields data. The doc['field_name'] can be used to access specific field data within a document (the document in question is usually derived by the context the script is used). Document fields are very fast to access since they end up being loaded into memory (all the relevant field values/tokens are loaded to memory). Note, however, that the doc[...] notation only allows for simple valued fields (can’t return a json object from it) and makes sense only on non-analyzed or single term based fields.

The following data can be extracted from a field:

Stored fields can also be accessed when executing a script. Note, they are much slower to access compared with document fields, as they are not loaded into memory. They can be simply accessed using _fields['my_field_name'].value or _fields['my_field_name'].values.

When using scripting for calculating the score of a document (for instance, with the function_score query), you can access the score using the _score variable inside of a Groovy script.

The source field can also be accessed when executing a script. The source field is loaded per doc, parsed, and then provided to the script for evaluation. The _source forms the context under which the source field can be accessed, for example _source.obj2.obj1.field3.

Accessing _source is much slower compared to using _doc but the data is not loaded into memory. For a single field access _fields may be faster than using _source due to the extra overhead of potentially parsing large documents. However, _source may be faster if you access multiple fields or if the source has already been loaded for other purposes.

There are several built in functions that can be used within scripts. They include:

When dividing two numbers using MVEL based scripts, the engine tries to be smart and adheres to the default behaviour of java. This means if you divide two integers (you might have configured the fields as integer in the mapping), the result will also be an integer. This means, if a calculation like 1/num is happening in your scripts and num is an integer with the value of 8, the result is 0 even though you were expecting it to be 0.125. You may need to enforce precision by explicitly using a double like 1.0/num in order to get the expected result.