elasticsearch/docs/reference/modules/scripting/painless.asciidoc

[[modules-scripting-painless]]
=== Painless Scripting Language

experimental[The Painless scripting language is new and is still marked as experimental. The syntax or API may be changed in the future in non-backwards compatible ways if required.]

_Painless_ is a simple, secure scripting language available in Elasticsearch
by default. It is designed specifically for use with Elasticsearch and can
safely be used with `inline` and `stored` scripting, which is enabled by
default.

A Painless script is essentially a single function. Painless does not provide support
for defining multiple functions within a script. The Painless syntax is similar to
http://groovy-lang.org/index.html[Groovy].

You can use Painless anywhere a script can be used in Elasticsearch--simply set the `lang` parameter
to `painless`.

[[painless-features]]
[float]
== Painless Features

* Control flow: `for` loops, `while` loops, `do/while` loops, `if/else`

* Fully Typed: all available types/methods described in <<painless-api, Painless API>>

* Arithmetic operators: multiplication `*`, division `/`, addition `+`, subtraction `-`, precedence `( )`

* Comparison operators: less than `<`, less than or equal to `<=`, greater than `>`, greater than or equal to `>=`, equal to `==`, and not equal to `!=`, reference equals `===`, reference not equals `!==`

* Boolean operators: not `!`, and `&&`, or `||`

* Bitwise operators: shift left `<<`, shift right `>>`, unsigned shift `>>>`, and `&`, or `|`, xor `^`, not `~`

* Shortcuts for list, map access using the dot `.` operator

* Native support for regular expressions with `/pattern/`, `=~`, and `==~`


[[painless-examples]]
[float]
== Painless Examples

To illustrate how Painless works, let's load some hockey stats into an Elasticsearch index:

[source,js]
----------------------------------------------------------------
PUT hockey/player/_bulk?refresh
{"index":{"_id":1}}
{"first":"johnny","last":"gaudreau","goals":[9,27,1],"assists":[17,46,0],"gp":[26,82,1]}
{"index":{"_id":2}}
{"first":"sean","last":"monohan","goals":[7,54,26],"assists":[11,26,13],"gp":[26,82,82]}
{"index":{"_id":3}}
{"first":"jiri","last":"hudler","goals":[5,34,36],"assists":[11,62,42],"gp":[24,80,79]}
{"index":{"_id":4}}
{"first":"micheal","last":"frolik","goals":[4,6,15],"assists":[8,23,15],"gp":[26,82,82]}
{"index":{"_id":5}}
{"first":"sam","last":"bennett","goals":[5,0,0],"assists":[8,1,0],"gp":[26,1,0]}
{"index":{"_id":6}}
{"first":"dennis","last":"wideman","goals":[0,26,15],"assists":[11,30,24],"gp":[26,81,82]}
{"index":{"_id":7}}
{"first":"david","last":"jones","goals":[7,19,5],"assists":[3,17,4],"gp":[26,45,34]}
{"index":{"_id":8}}
{"first":"tj","last":"brodie","goals":[2,14,7],"assists":[8,42,30],"gp":[26,82,82]}
{"index":{"_id":39}}
{"first":"mark","last":"giordano","goals":[6,30,15],"assists":[3,30,24],"gp":[26,60,63]}
{"index":{"_id":10}}
{"first":"mikael","last":"backlund","goals":[3,15,13],"assists":[6,24,18],"gp":[26,82,82]}
{"index":{"_id":11}}
{"first":"joe","last":"colborne","goals":[3,18,13],"assists":[6,20,24],"gp":[26,67,82]}
----------------------------------------------------------------
// CONSOLE
// TESTSETUP

[float]
=== Accessing Doc Values from Painless

Document values can be accessed from a `Map<String,def>` named `doc`.

For example, the following script calculates a player's total goals. This example uses a strongly typed `int` and a `for` loop.

[source,js]
----------------------------------------------------------------
GET hockey/_search
{
  "query": {
    "function_score": {
      "script_score": {
        "script": {
          "lang": "painless",
          "inline": "int total = 0; for (int i = 0; i < doc['goals'].length; ++i) { total += doc['goals'][i]; } return total;"
        }
      }
    }
  }
}
----------------------------------------------------------------
// CONSOLE

Alternatively, you could do the same thing using a script field instead of a function score:

[source,js]
----------------------------------------------------------------
GET hockey/_search
{
  "query": {
    "match_all": {}
  },
  "script_fields": {
    "total_goals": {
      "script": {
        "lang": "painless",
        "inline": "int total = 0; for (int i = 0; i < doc['goals'].length; ++i) { total += doc['goals'][i]; } return total;"
      }
    }
  }
}
----------------------------------------------------------------
// CONSOLE

The following example uses a Painless script to sort the players by their combined first and last names. The names are accessed using
`doc['first'].value` and `doc['last'].value`.

[source,js]
----------------------------------------------------------------
GET hockey/_search
{
  "query": {
    "match_all": {}
  },
  "sort": {
    "_script": {
      "type": "string",
      "order": "asc",
      "script": {
        "lang": "painless",
        "inline": "doc['first.keyword'].value + ' ' + doc['last.keyword'].value"
      }
    }
  }
}
----------------------------------------------------------------
// CONSOLE

[float]
=== Updating Fields with Painless

You can also easily update fields. You access the original source for a field as `ctx._source.<field-name>`.

First, let's look at the source data for a player by submitting the following request:

[source,js]
----------------------------------------------------------------
GET hockey/_search
{
  "fields": [
    "_id",
    "_source"
  ],
  "query": {
    "term": {
      "_id": 1
    }
  }
}
----------------------------------------------------------------
// CONSOLE

To change player 1's last name to `hockey`, simply set `ctx._source.last` to the new value:

[source,js]
----------------------------------------------------------------
POST hockey/player/1/_update
{
  "script": {
    "lang": "painless",
    "inline": "ctx._source.last = params.last",
    "params": {
      "last": "hockey"
    }
  }
}
----------------------------------------------------------------
// CONSOLE

You can also add fields to a document. For example, this script adds a new field that contains
the player's nickname,  _hockey_.

[source,js]
----------------------------------------------------------------
POST hockey/player/1/_update
{
  "script": {
    "lang": "painless",
    "inline": "ctx._source.last = params.last; ctx._source.nick = params.nick",
    "params": {
      "last": "gaudreau",
      "nick": "hockey"
    }
  }
}
----------------------------------------------------------------
// CONSOLE

[float]
[[modules-scripting-painless-regex]]
=== Regular expressions

Painless's native support for regular expressions has syntax constructs:

* `/pattern/`: Pattern literals create patterns. This is the only way to create
a pattern in painless. The pattern inside the `/`s are just
http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java regular expressions].
See <<modules-scripting-painless-regex-flags>> for more.
* `=~`: The find operator return a `boolean`, `true` if a subsequence of the
text matches, `false` otherwise.
* `==~`: The match operator returns a `boolean`, `true` if the text matches,
`false` if it doesn't.

Using the find operator (`=~`) you can update all hockey players with "b" in
their last name:

[source,js]
----------------------------------------------------------------
POST hockey/player/_update_by_query
{
  "script": {
    "lang": "painless",
    "inline": "if (ctx._source.last =~ /b/) {ctx._source.last += \"matched\"} else {ctx.op = 'noop'}"
  }
}
----------------------------------------------------------------
// CONSOLE

Using the match operator (`==~`) you can update all the hockey players who's
names start with a consonant and end with a vowel:

[source,js]
----------------------------------------------------------------
POST hockey/player/_update_by_query
{
  "script": {
    "lang": "painless",
    "inline": "if (ctx._source.last ==~ /[^aeiou].*[aeiou]/) {ctx._source.last += \"matched\"} else {ctx.op = 'noop'}"
  }
}
----------------------------------------------------------------
// CONSOLE

Or you can use the `Pattern.matcher` directory to get a `Matcher` instance and
remove all of the vowels in all of their names:

[source,js]
----------------------------------------------------------------
POST hockey/player/_update_by_query
{
  "script": {
    "lang": "painless",
    "inline": "ctx._source.last = /[aeiou]/.matcher(ctx._source.last).replaceAll('')"
  }
}
----------------------------------------------------------------
// CONSOLE


Note: all of the `_update_by_query` examples above could really do with a
`query` to limit the data that they pull back. While you *could* use a
<<query-dsl-script-query>> it wouldn't be as efficient as using any other query
because script queries aren't able to use the inverted index to limit the
documents that they have to check.

We intentionally don't allow scripts to call `Pattern.compile` to get a new
pattern on the fly because building a `Pattern` is (comparatively) slow.
Pattern literals (`/apattern/`) have fancy constant extraction so no matter
where they show up in the painless script they are built only when the script
is first used. It is fairly similar to how `String` literals work in Java.

[float]
[[modules-scripting-painless-regex-flags]]
==== Regular expression flags

You can define flags on patterns in Painless by adding characters after the
trailing `/` like `/foo/i` or `/foo \w #comment/iUx`. Painless exposes all the
flags from
https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[Java's Pattern class]
using these characters:

[cols="<,<,<",options="header",]
|=======================================================================
| Character | Java Constant | Example
|`c` | CANON_EQ                  | `'å' ==~ /å/c` (open in hex editor to see)
|`i` | CASE_INSENSITIVE          | `'A' ==~ /a/i`
|`l` | LITERAL                   | `'[a]' ==~ /[a]/l`
|`m` | MULTILINE                 | `'a\nb\nc' =~ /^b$/m`
|`s` | DOTALL (aka single line)  | `'a\nb\nc' =~ /.b./s`
|`U` | UNICODE_CHARACTER_CLASS   | `'Ɛ' ==~ /\\w/U`
|`u` | UNICODE_CASE              | `'Ɛ' ==~ /ɛ/iu`
|`x` | COMMENTS (aka extended)   | `'a' ==~ /a #comment/x`
|=======================================================================


[[painless-api]]
[float]
== Painless API

The following types are available for use in the Painless language. Most types and methods map directly to their Java equivalents--for more information, see the corresponding https://docs.oracle.com/javase/8/docs/api/java/lang/package-summary.html[Javadoc].


[float]
=== Dynamic Types

* `def` (This type can be used to represent any other type.)

[float]
=== Basic Types

* `void`
* `boolean`
* `short`
* `char`
* `int`
* `long`
* `float`
* `double`

[float]
=== Complex Types

Non-static methods/members in superclasses are available to subclasses.
Generic types with unspecified generic parameters are parameters of type `def`.

-----
ArithmeticException extends Exception
   <init>()
-----

-----
ArrayList extends List
   <init>()
-----

-----
ArrayList<Object> extends List<Object>
   <init>()
-----

-----
ArrayList<String> extends List<String>
    <init>()
-----

-----
Boolean extends Object
   <init>(boolean)
   static Boolean valueOf(boolean)
   boolean booleanValue()
-----

-----
Character extends Object
    <init>(char)
    static Character valueOf(char)
    char charValue()
    static char MIN_VALUE
    static char MAX_VALUE
-----

-----
CharSequence extends Object
    char charAt(int)
    int length()
-----

-----
Collection extends Object
    boolean add(def)
    void clear()
    boolean contains(def)
    boolean isEmpty()
    Iterator iterator()
    boolean remove(def)
    int size()
-----

-----
Collection<Object> extends Object
    boolean add(Object)
    void clear()
    boolean contains(Object)
    boolean isEmpty()
    Iterator iterator()
    boolean remove(Object)
    int size()
-----

-----
Collection<String> extends Object
    boolean add(String)
    void clear()
    boolean contains(String)
    boolean isEmpty()
    Iterator iterator()
    boolean remove(String)
    int size()
-----

-----
Double extends Number
    <init>(double)
    static Double valueOf(double)
    static double MIN_VALUE
    static double MAX_VALUE
-----

-----
Exception extends Object
    String getMessage()
-----

-----
Float extends Number
    <init>(float)
    static Float valueOf(float)
    static float MIN_VALUE
    static float MAX_VALUE
-----

-----
HashMap extends Map
    <init>()
-----

-----
HashMap<Object,Object> extends Map<Object,Object>
    <init>()
-----

-----
HashMap<String,def> extends Map<String,def>
    <init>()
-----

-----
HashMap<String,Object> extends Map<String,Object>
    <init>()
-----

-----
IllegalArgument extends Exception
    <init>()
-----

-----
IllegalState extends Exception
    <init>()
-----

-----
Integer extends Number
    <init>(int)
    static Integer valueOf(int)
    static int MIN_VALUE
    static int MAX_VALUE
-----

-----
Iterator extends Object
    boolean hasNext()
    def next()
    void remove()
-----

-----
Iterator<String> extends Object
    boolean hasNext()
    String next()
    void remove()
-----

-----
List extends Collection
    def set(int, def)
    def get(int)
    def remove(int)
-----

-----
List<Object> extends Collection
    Object set(int, Object)
    Object get(int)
    Object remove(int)
-----

-----
List<String> extends Collection
    String set(int, String)
    String get(int)
    String remove(int)
-----

-----
Long extends Number
    <init>(long)
    static Long valueOf(long)
    static long MIN_VALUE
    static long MAX_VALUE
-----

-----
Map extends Object
    def put (def, def)
    def get (def)
    def remove (def)
    boolean isEmpty()
    int size()
    boolean containsKey(def)
    boolean containsValue(def)
    Set keySet()
    Collection values()
-----

-----
Map<Object,Object> extends Object
    Object put (Object, Object)
    Object get (Object)
    Object remove (Object)
    boolean isEmpty()
    int size()
    boolean containsKey(Object)
    boolean containsValue(Object)
    Set keySet()
    Collection values()
-----

-----
Map<String,def> extends Object
    def put (String, def)
    def get (String)
    def remove (String)
    boolean isEmpty()
    int size()
    boolean containsKey(String)
    boolean containsValue(def)
    Set<String> keySet()
    Collection values()
-----

-----
Map<String,Object> extends Object
    Object put (String, Object)
    Object get (String)
    Object remove (String)
    boolean isEmpty()
    int size()
    boolean containsKey(String)
    boolean containsValue(Object)
    Set<String> keySet()
    Collection values()
-----

-----
Number extends Object
    short shortValue()
    short shortValue()
    int intValue()
    long longValue()
    float floatValue()
    double doubleValue()
-----

-----
Object
    String toString()
    boolean equals(Object)
    int hashCode()
-----

-----
Set extends Collection
-----

-----
Set<Object> extends Collection<Object>
-----

-----
Set<String> extends Collection<String>
-----

-----
Short extends Number
    <init>(short)
    static Short valueOf(short)
    static short MIN_VALUE
    static short MAX_VALUE
-----

-----
String extends CharSequence
    <init>(String)
    int codePointAt(int)
    int compareTo(String)
    String concat(String)
    boolean endsWith(String)
    int indexOf(String, int)
    boolean isEmpty()
    String replace(CharSequence, CharSequence)
    boolean startsWith(String)
    String substring(int, int)
    char[] toCharArray()
    String trim()
-----

-----
NumberFormatException extends Exception
    <init>()
-----

-----
Void extends Object
-----

[float]
==== Utility Classes

-----
Math
   static double abs(double)
   static float fabs(float)
   static long labs(long)
   static int iabs(int)
   static double acos(double)
   static double asin(double)
   static double atan(double)
   static double atan2(double)
   static double cbrt(double)
   static double ceil(double)
   static double cos(double)
   static double cosh(double)
   static double exp(double)
   static double expm1(double)
   static double floor(double)
   static double hypt(double, double)
   static double abs(double)
   static double log(double)
   static double log10(double)
   static double log1p(double)
   static double max(double, double)
   static float fmax(float, float)
   static long lmax(long, long)
   static int imax(int, int)
   static double min(double, double)
   static float fmin(float, float)
   static long lmin(long, long)
   static int imin(int, int)
   static double pow(double, double)
   static double random()
   static double rint(double)
   static long round(double)
   static double sin(double)
   static double sinh(double)
   static double sqrt(double)
   static double tan(double)
   static double tanh(double)
   static double toDegrees(double)
   static double toRadians(double)
-----

-----
Utility
   static boolean NumberToboolean(Number)
   static char NumberTochar(Number)
   static Boolean NumberToBoolean(Number)
   static Short NumberToShort(Number)
   static Character NumberToCharacter(Number)
   static Integer NumberToInteger(Number)
   static Long NumberToLong(Number)
   static Float NumberToFloat(Number)
   static Double NumberToDouble(Number)
   static byte booleanTobyte(boolean)
   static short booleanToshort(boolean)
   static char booleanTochar(boolean)
   static int booleanToint(boolean)
   static long booleanTolong(boolean)
   static float booleanTofloat(boolean)
   static double booleanTodouble(boolean)
   static Integer booleanToInteger(boolean)
   static byte BooleanTobyte(Boolean)
   static short BooleanToshort(Boolean)
   static char BooleanTochar(Boolean)
   static int BooleanToint(Boolean)
   static long BooleanTolong(Boolean)
   static float BooleanTofloat(Boolean)
   static double BooleanTodouble(Boolean)
   static Byte BooleanToByte(Boolean)
   static Short BooleanToShort(Boolean)
   static Character BooleanToCharacter(Boolean)
   static Integer BooleanToInteger(Boolean)
   static Long BooleanToLong(Boolean)
   static Float BooleanToFloat(Boolean)
   static Double BooleanToDouble(Boolean)
   static boolean byteToboolean(byte)
   static Short byteToShort(byte)
   static Character byteToCharacter(byte)
   static Integer byteToInteger(byte)
   static Long byteToLong(byte)
   static Float byteToFloat(byte)
   static Double byteToDouble(byte)
   static boolean ByteToboolean(Byte)
   static char ByteTochar(Byte)
   static boolean shortToboolean(short)
   static Byte shortToByte(short)
   static Character shortToCharacter(short)
   static Integer shortToInteger(short)
   static Long shortToLong(short)
   static Float shortToFloat(short)
   static Double shortToDouble(short)
   static boolean ShortToboolean(Short)
   static char ShortTochar(Short)
   static boolean charToboolean(char)
   static Byte charToByte(char)
   static Short charToShort(char)
   static Integer charToInteger(char)
   static Long charToLong(char)
   static Float charToFloat(char)
   static Double charToDouble(char)
   static boolean CharacterToboolean(Character)
   static byte CharacterTobyte(Character)
   static short CharacterToshort(Character)
   static int CharacterToint(Character)
   static long CharacterTolong(Character)
   static float CharacterTofloat(Character)
   static double CharacterTodouble(Character)
   static Boolean CharacterToBoolean(Character)
   static Byte CharacterToByte(Character)
   static Short CharacterToShort(Character)
   static Integer CharacterToInteger(Character)
   static Long CharacterToLong(Character)
   static Float CharacterToFloat(Character)
   static Double CharacterToDouble(Character)
   static boolean intToboolean(int)
   static Byte intToByte(int)
   static Short intToShort(int)
   static Character intToCharacter(int)
   static Long intToLong(int)
   static Float intToFloat(int)
   static Double intToDouble(int)
   static boolean IntegerToboolean(Integer)
   static char IntegerTochar(Integer)
   static boolean longToboolean(long)
   static Byte longToByte(long)
   static Short longToShort(long)
   static Character longToCharacter(long)
   static Integer longToInteger(long)
   static Float longToFloat(long)
   static Double longToDouble(long)
   static boolean LongToboolean(Long)
   static char LongTochar(Long)
   static boolean floatToboolean(float)
   static Byte floatToByte(float)
   static Short floatToShort(float)
   static Character floatToCharacter(float)
   static Integer floatToInteger(float)
   static Long floatToLong(float)
   static Double floatToDouble(float)
   static boolean FloatToboolean(Float)
   static char FloatTochar(Float)
   static boolean doubleToboolean(double)
   static Byte doubleToByte(double)
   static Short doubleToShort(double)
   static Character doubleToCharacter(double)
   static Integer doubleToInteger(double)
   static Long doubleToLong(double)
   static Float doubleToFloat(double)
   static boolean DoubleToboolean(Double)
   static char DoubleTochar(Double)
-----

-----
Def
    static boolean defToboolean(def)
    static byte defTobyte(def)
    static short defToshort(def)
    static char defTochar(def)
    static int defToint(def)
    static long defTolong(def)
    static float defTofloat(def)
    static double defTodouble(def)
    static Boolean defToBoolean(def)
    static Byte defToByte(def)
    static Character defToCharacter(def)
    static Integer defToInteger(def)
    static Long defToLong(def)
    static Float defToFloat(def)
    static Double defToDouble(def)
-----