[[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 <> * 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` 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'].value + ' ' + doc['last'].value" } } } } ---------------------------------------------------------------- // CONSOLE [float] === Updating Fields with Painless You can also easily update fields. You access the original source for a field as `ctx._source.`. 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 <> 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 <> 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 () ----- ----- ArrayList extends List () ----- ----- ArrayList extends List () ----- ----- ArrayList extends List () ----- ----- Boolean extends Object (boolean) static Boolean valueOf(boolean) boolean booleanValue() ----- ----- Character extends Object (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 extends Object boolean add(Object) void clear() boolean contains(Object) boolean isEmpty() Iterator iterator() boolean remove(Object) int size() ----- ----- Collection extends Object boolean add(String) void clear() boolean contains(String) boolean isEmpty() Iterator iterator() boolean remove(String) int size() ----- ----- Double extends Number (double) static Double valueOf(double) static double MIN_VALUE static double MAX_VALUE ----- ----- Exception extends Object String getMessage() ----- ----- Float extends Number (float) static Float valueOf(float) static float MIN_VALUE static float MAX_VALUE ----- ----- HashMap extends Map () ----- ----- HashMap extends Map () ----- ----- HashMap extends Map () ----- ----- HashMap extends Map () ----- ----- IllegalArgument extends Exception () ----- ----- IllegalState extends Exception () ----- ----- Integer extends Number (int) static Integer valueOf(int) static int MIN_VALUE static int MAX_VALUE ----- ----- Iterator extends Object boolean hasNext() def next() void remove() ----- ----- Iterator extends Object boolean hasNext() String next() void remove() ----- ----- List extends Collection def set(int, def) def get(int) def remove(int) ----- ----- List extends Collection Object set(int, Object) Object get(int) Object remove(int) ----- ----- List extends Collection String set(int, String) String get(int) String remove(int) ----- ----- Long extends Number (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 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 extends Object def put (String, def) def get (String) def remove (String) boolean isEmpty() int size() boolean containsKey(String) boolean containsValue(def) Set keySet() Collection values() ----- ----- Map extends Object Object put (String, Object) Object get (String) Object remove (String) boolean isEmpty() int size() boolean containsKey(String) boolean containsValue(Object) Set 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 extends Collection ----- ----- Set extends Collection ----- ----- Short extends Number (short) static Short valueOf(short) static short MIN_VALUE static short MAX_VALUE ----- ----- String extends CharSequence (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 () ----- ----- 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) -----