Built-in query language functions
Like constants and variables, the query language has many built-in functions that you can call without any import or setup. Built-in functions are a better choice than user-defined functions in query strings for these reasons:
- They are usually faster than Groovy closures, which the engine calls with boxed arguments and an
Objectresult. - Most of them return a null result for null input instead of throwing an error.
- They need no extra code: you call them by name.
Use built-in functions in query strings
Built-in functions range from simple mathematical functions to date-time arithmetic, string parsing, and more. The examples below show a few of them. For the complete list, see Auto-imported functions.
The following query calculates the absolute value of a column using the built-in abs function:
The following query parses a column of strings containing integers into Java primitive int values using parseInt:
The following query uses the built-in and function to evaluate whether three columns are all true:
Unlike most built-in functions, and throws an error if any argument is null. To treat nulls as a fixed value, use the and overload that takes a replacement value for nulls.
Most other built-in functions return a null result for null input. For example, the following query calls the built-in sin function on a column that contains null values. SinX is null in those rows:
Add Java classes to the query library
Built-in functions cover common needs, and query strings can also use other Java classes. The query library holds the imports that query strings can use. By default, it includes:
- The
java.langandjava.utilpackages - Specific classes from other packages
- The static methods of the built-in function classes
That is why you can call abs or parseInt without a class name, and refer to a class such as Integer by its simple name, without its package. For the complete list of default imports, see Auto-imported functions.
A Groovy import statement makes a class available to your Groovy script, not to query strings. To use a class from any other package in a query string, you have these options:
- Use its fully qualified name, such as
java.net.URI. - Import it into the query library with
importClass, then use its simple name, such asURI. - Import its whole package with
importPackage, then use the simple name of any public class in it.
To get the query library in Groovy:
- Call
getContextonExecutionContextto get the current execution context. - Call
getQueryLibraryon that context to get itsQueryLibrary.
The example in Import static methods chains both calls.
For an example that imports a class, see Import Java classes.
Import static methods
You can also import a class's static methods into the query library with importStatic, so query strings can call them without the class name. The following example imports the static methods of java.lang.StrictMath and calls fma without a class name.
Note
Numeric, a built-in class, also defines acos, exp, and getExponent. After importStatic imports StrictMath, a call to any of those names without a class name is ambiguous. The example prefixes each one with a class name:
StrictMath.acosandStrictMath.getExponentwork without an import, because the query library includesjava.langby default.expneeds the fully qualified nameio.deephaven.function.Numeric.exp. The query library imports the static methods ofNumeric, but not the class nameNumeric.
The import lasts for the rest of the execution context, not just this query. After it, a call without a class name to any method that both classes define for the same argument type is ambiguous in every query string. That includes the earlier examples on this page, such as abs on a long or sin on a double. Prefix those calls with a class name too.
Other names switch to the StrictMath method with no error. After the import, min(A, B) on two double or int values calls StrictMath.min. That method treats a Deephaven null as an ordinary number, so when A is null, min(A, B) returns null instead of B. To keep Deephaven's null handling, write io.deephaven.function.Numeric.min(A, B).
Related documentation
- Execution context
- Query string overview
- Built-in constants
- Built-in variables
- Ternary conditional operator
- Groovy closures in queries
- Data types in Deephaven
- Java objects in query strings
- Auto-imported functions
- Math functions
- Logic functions
- Parse functions
- Nulls
- Strings
emptyTablenewTablebooleanColupdateExecutionContextJavadocQueryLibraryJavadoc