Wherever scripting is supported in the Elasticsearch API, the syntax follows the same pattern:

  "script": {
    "lang":   "...",  
    "source" | "id": "...", 
    "params": { ... } 
  }

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 parametersedit

  "source": "doc['my_field'] * 2"

  "source": "doc['my_field'] * multiplier",
  "params": {
    "multiplier": 2
  }

Short script formedit

A 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 scriptsedit

Scripts may be stored in and retrieved from the cluster state using the _scripts end-point.

If the Elasticsearch security features are enabled, you must have the following privileges to create, retrieve, and delete stored scripts:

For more information, see Security privileges.

Request examplesedit

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

You may also specify a context as part of the url path to compile a stored script against that specific context in the form of /_scripts/{id}/{context}:

POST _scripts/calculate-score/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 twitter/_search
{
  "query": {
    "script_score": {
      "query": {
        "match": {
            "message": "some message"
        }
      },
      "script": {
        "id": "calculate-score",
        "params": {
          "my_modifier": 2
        }
      }
    }
  }
}

And deleted with:

DELETE _scripts/calculate-score

Search templatesedit

You can also use the _scripts API to store search templates. Search templates save specific search requests with placeholder values, called template parameters.

You can use stored search templates to run searches without writing out the entire query. Just provide the stored template’s ID and the template parameters. This is useful when you want to run a commonly used query quickly and without mistakes.

Search templates use the mustache templating language. See Search Template for more information and examples.

Script cachingedit

All 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.

Script errorsedit

Elasticsearch returns error details when there is a compliation or runtime exception. The contents of this response are useful for tracking down the problem.

The contents of position are experimental and subject to change.