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:

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.lang and java.util packages
  • 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_class from the query_library module, then use its simple name, such as URI.
  • 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.acos and StrictMath.getExponent work without an import, because the query library includes java.lang by default.
  • exp needs the fully qualified name io.deephaven.function.Numeric.exp. The query library imports the static methods of Numeric, but not the class name Numeric.

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).