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. Use these built-in functions instead of Python functions or other user-defined functions in query strings for these reasons:
- They are faster than Python functions.
- 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.
For more on the performance difference, see The Python-Java boundary.
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.
To use a class from any other package, you have these options:
- Use its fully qualified name, such as
java.net.URI. - Import it with
import_classfrom thequery_librarymodule, then use its simple name, such asURI. - Import its whole package with
import_package, then use the simple name of any public class in it.
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 import_static, 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 import_static 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
- The Python-Java boundary
- Execution context
- Query string overview
- Built-in constants
- Built-in variables
- Ternary conditional operator
- Python functions in query strings
- Data types in Deephaven and Python
- Java objects in query strings
- Auto-imported functions
- Math functions
- Logic functions
- Parse functions
- Nulls
- Strings
empty_tablenew_tablebool_colupdatequery_libraryPydoc