-
Notifications
You must be signed in to change notification settings - Fork 25.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* master: Remove the index thread pool (#29556) Remove extra copy in ScriptDocValues.Strings Fix full cluster restart test recovery (#29545) Fix binary doc values fetching in _search (#29567) Mutes failing MovAvgIT tests Fix the assertion message for an incorrect current version. (#29572) Fix the version ID for v5.6.10. (#29570) Painless Spec Documentation Clean Up (#29441) Add versions 5.6.10 and 6.2.5 [TEST] test against scaled value instead of fixed epsilon in MovAvgIT Remove `flatSettings` support from request classes (#29560) MapperService to wrap a single DocumentMapper. (#29511) Fix dependency checks on libs when generating Eclipse configuration. (#29550) Add null_value support to geo_point type (#29451) Add documentation about the include_type_name option. (#29555) Enforce translog access via engine (#29542)
- Loading branch information
Showing
84 changed files
with
1,034 additions
and
821 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,13 @@ | ||
| ["appendix",id="painless-api-reference"] | ||
| = Painless API Reference | ||
| [[painless-api-reference]] | ||
| == Painless API Reference | ||
|
|
||
| Painless has a strict whitelist for methods and | ||
| classes to make sure that all painless scripts are secure and fast. Most of | ||
| these methods are exposed directly from the JRE while others are part of | ||
| Elasticsearch or Painless itself. Below is a list of all available methods | ||
| grouped under the classes on which you can call them. Clicking on the method | ||
| name takes you to the documentation for the method. | ||
|
|
||
| NOTE: Methods defined in the JRE also have a `(java 9)` link which can be used | ||
| to see the method's documentation in Java 9 while clicking on the method's name | ||
| goes to the Java 8 documentation. Usually these aren't different but it is | ||
| worth going to the version that matches the version of Java you are using to | ||
| run Elasticsearch just in case. | ||
| Painless has a strict whitelist for methods and classes to ensure all | ||
| painless scripts are secure. Most of these methods are exposed directly | ||
| from the Java Runtime Enviroment (JRE) while others are part of | ||
| Elasticsearch or Painless itself. Below is a list of all available | ||
| classes grouped with their respected methods. Clicking on the method | ||
| name takes you to the documentation for that specific method. Methods | ||
| defined in the JRE also have a `(java 9)` link which can be used to see | ||
| the method's documentation in Java 9. | ||
|
|
||
| include::painless-api-reference/index.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,172 @@ | ||
| [[painless-casting]] | ||
| === Casting | ||
|
|
||
| Casting is the conversion of one type to another. Implicit casts are casts that | ||
| occur automatically, such as during an assignment operation. Explicit casts are | ||
| casts where you use the casting operator to explicitly convert one type to | ||
| another. This is necessary during operations where the cast cannot be inferred. | ||
|
|
||
| To cast to a new type, precede the expression by the new type enclosed in | ||
| parentheses, for example | ||
| `(int)x`. | ||
|
|
||
| The following sections specify the implicit casts that can be performed and the | ||
| explicit casts that are allowed. The only other permitted cast is casting | ||
| a single character `String` to a `char`. | ||
|
|
||
| *Grammar:* | ||
| [source,ANTLR4] | ||
| ---- | ||
| cast: '(' TYPE ')' expression | ||
| ---- | ||
|
|
||
| [[numeric-casting]] | ||
| ==== Numeric Casting | ||
|
|
||
| The following table shows the allowed implicit and explicit casts between | ||
| numeric types. Read the table by row. To find out if you need to explicitly | ||
| cast from type A to type B, find the row for type A and scan across to the | ||
| column for type B. | ||
|
|
||
| IMPORTANT: Explicit casts between numeric types can result in some data loss. A | ||
| smaller numeric type cannot necessarily accommodate the value from a larger | ||
| numeric type. You might also lose precision when casting from integer types | ||
| to floating point types. | ||
|
|
||
| |==== | ||
| | | byte | short | char | int | long | float | double | ||
| | byte | | implicit | implicit | implicit | implicit | implicit | implicit | ||
| | short | explicit | | explicit | implicit | implicit | implicit | implicit | ||
| | char | explicit | explicit | | implicit | implicit | implicit | implicit | ||
| | int | explicit | explicit | explicit | | implicit | implicit | implicit | ||
| | long | explicit | explicit | explicit | explicit | | implicit | implicit | ||
| | float | explicit | explicit | explicit | explicit | explicit | | implicit | ||
| | double | explicit | explicit | explicit | explicit | explicit | explicit | | ||
| |==== | ||
|
|
||
|
|
||
| Example(s) | ||
| [source,Java] | ||
| ---- | ||
| int a = 1; // Declare int variable a and set it to the literal | ||
| // value 1 | ||
| long b = a; // Declare long variable b and set it to int variable | ||
| // a with an implicit cast to convert from int to long | ||
| short c = (short)b; // Declare short variable c, explicitly cast b to a | ||
| // short, and assign b to c | ||
| byte d = a; // ERROR: Casting an int to a byte requires an explicit | ||
| // cast | ||
| double e = (double)a; // Explicitly cast int variable a to a double and assign | ||
| // it to the double variable e. The explicit cast is | ||
| // allowed, but it is not necessary. | ||
| ---- | ||
|
|
||
| [[reference-casting]] | ||
| ==== Reference Casting | ||
|
|
||
| A reference type can be implicitly cast to another reference type as long as | ||
| the type being cast _from_ is a descendant of the type being cast _to_. A | ||
| reference type can be explicitly cast _to_ if the type being cast to is a | ||
| descendant of the type being cast _from_. | ||
|
|
||
| *Examples:* | ||
| [source,Java] | ||
| ---- | ||
| List x; // Declare List variable x | ||
| ArrayList y = new ArrayList(); // Declare ArrayList variable y and assign it a | ||
| // newly allocated ArrayList [1] | ||
| x = y; // Assign Arraylist y to List x using an | ||
| // implicit cast | ||
| y = (ArrayList)x; // Explicitly cast List x to an ArrayList and | ||
| // assign it to ArrayList y | ||
| x = (List)y; // Set List x to ArrayList y using an explicit | ||
| // cast (the explicit cast is not necessary) | ||
| y = x; // ERROR: List x cannot be implicitly cast to | ||
| // an ArrayList, an explicit cast is required | ||
| Map m = y; // ERROR: Cannot implicitly or explicitly cast [2] | ||
| // an ArrayList to a Map, no relationship | ||
| // exists between the two types. | ||
| ---- | ||
| [1] `ArrayList` is a descendant of the `List` type. | ||
| [2] `Map` is unrelated to the `List` and `ArrayList` types. | ||
|
|
||
| [[def-type-casting]] | ||
| ==== def Type Casting | ||
| All primitive and reference types can always be implicitly cast to | ||
| `def`. While it is possible to explicitly cast to `def`, it is not necessary. | ||
|
|
||
| However, it is not always possible to implicitly cast a `def` to other | ||
| primitive and reference types. An explicit cast is required if an explicit | ||
| cast would normally be required between the non-def types. | ||
|
|
||
|
|
||
| *Examples:* | ||
| [source,Java] | ||
| ---- | ||
| def x; // Declare def variable x and set it to null | ||
| x = 3; // Set the def variable x to the literal 3 with an implicit | ||
| // cast from int to def | ||
| double a = x; // Declare double variable a and set it to def variable x, | ||
| // which contains a double | ||
| int b = x; // ERROR: Results in a run-time error because an explicit cast is | ||
| // required to cast from a double to an int | ||
| int c = (int)x; // Declare int variable c, explicitly cast def variable x to an | ||
| // int, and assign x to c | ||
| ---- | ||
|
|
||
| [[boxing-unboxing]] | ||
| ==== Boxing and Unboxing | ||
|
|
||
| Boxing is where a cast is used to convert a primitive type to its corresponding | ||
| reference type. Unboxing is the reverse, converting a reference type to the | ||
| corresponding primitive type. | ||
|
|
||
| There are two places Painless performs implicit boxing and unboxing: | ||
|
|
||
| * When you call methods, Painless automatically boxes and unboxes arguments | ||
| so you can specify either primitive types or their corresponding reference | ||
| types. | ||
| * When you use the `def` type, Painless automatically boxes and unboxes as | ||
| needed when converting to and from `def`. | ||
|
|
||
| The casting operator does not support any way to explicitly box a primitive | ||
| type or unbox a reference type. | ||
|
|
||
| If a primitive type needs to be converted to a reference type, the Painless | ||
| reference type API supports methods that can do that. However, under normal | ||
| circumstances this should not be necessary. | ||
|
|
||
| *Examples:* | ||
| [source,Java] | ||
| ---- | ||
| Integer x = 1; // ERROR: not a legal implicit cast | ||
| Integer y = (Integer)1; // ERROR: not a legal explicit cast | ||
| int a = new Integer(1); // ERROR: not a legal implicit cast | ||
| int b = (int)new Integer(1); // ERROR: not a legal explicit cast | ||
| ---- | ||
|
|
||
| [[promotion]] | ||
| ==== Promotion | ||
|
|
||
| Promotion is where certain operations require types to be either a minimum | ||
| numerical type or for two (or more) types to be equivalent. | ||
| The documentation for each operation that has these requirements | ||
| includes promotion tables that describe how this is handled. | ||
|
|
||
| When an operation promotes a type or types, the resultant type | ||
| of the operation is the promoted type. Types can be promoted to def | ||
| at compile-time; however, at run-time, the resultant type will be the | ||
| promotion of the types the `def` is representing. | ||
|
|
||
| *Examples:* | ||
| [source,Java] | ||
| ---- | ||
| 2 + 2.0 // Add the literal int 2 and the literal double 2.0. The literal | ||
| // 2 is promoted to a double and the resulting value is a double. | ||
| def x = 1; // Declare def variable x and set it to the literal int 1 through | ||
| // an implicit cast | ||
| x + 2.0F // Add def variable x and the literal float 2.0. | ||
| // At compile-time the types are promoted to def. | ||
| // At run-time the types are promoted to float. | ||
| ---- |
Oops, something went wrong.