Built-in query language functions

Like constants and variables, there are many built-in functions that can be called from the query language with no additional imports or setup. These built-in functions should be used over Python or other user-defined functions in query strings for two reasons:

  • They are almost always more performant.
  • They handle null values gracefully.

For more on why, see The Python-Java boundary.

Built-in functions

Built-in functions range from simple mathematical functions to date-time arithmetic, string manipulation, and more.

The following query calculates the absolute value of a column using the built-in abs function:

from deephaven import empty_table

source = empty_table(10).update(["X = -ii", "AbsX = abs(X)"])

The following query parses a column of strings containing integers into Java primitive int values using parseInt:

from deephaven import empty_table
from random import choice


def rand_string_number() -> str:
    return choice([str(item) for item in list(range(10))])


source = empty_table(10).update("StringColumn = rand_string_number()")
result = source.update("IntegerColumn = parseInt(StringColumn)")

The following query uses the built-in and function to evaluate whether or not three different columns are all true:

from deephaven import new_table
from deephaven.column import bool_col

source = new_table(
    [
        bool_col("A", [True, True, True]),
        bool_col("B", [True, True, False]),
        bool_col("C", [True, False, True]),
    ]
)
result = source.update(["IsOk = and(A, B, C)"])

Built-in functions gracefully handle null values as input. For example, the following example calls the built-in sin function on a column that contains null values:

from deephaven import empty_table

source = empty_table(40).update(
    ["X = (ii % 3 != 0) ? 0.1 * ii : NULL_DOUBLE", "SinX = sin(X)"]
)

This page does not provide a comprehensive list of all built-ins. For the complete list of functions built into the query language, see Auto-imported functions.

Add Java classes to the query library

To use a non-default Java class in a Deephaven Query Language (DQL) query string, you must first import the class into DQL using Python. For this, Deephaven offers the query_library module.

The following example adds the java.net.URL class to the query library then uses it in table operations.

from deephaven import empty_table
from deephaven import query_library

query_library.import_class("java.net.URL")

source = empty_table(1).update(
    [
        "DeephavenUrl = new URL(`https://deephaven.io/`)",
        "Protocol = DeephavenUrl.getProtocol()",
        "Host = DeephavenUrl.getHost()",
        "Path = DeephavenUrl.getPath()",
    ]
)

You can also import static methods from a class into the query language to use them in table operations. The following example imports static methods from the java.lang.StrictMath class and uses them in table operations.

Note

import_static allows you to call methods without the class name. The class name is included in the examples below because methods of the same name also exist in the built-in io.deephaven.function.Numeric class.

In this case, you can no longer use just acos, exp, or any of the other method names that exist in both classes as it will be an ambiguous reference.

from deephaven import empty_table
from deephaven import query_library

query_library.import_static("java.lang.StrictMath")

source = empty_table(10).update(
    [
        "X = randomDouble(-1.67, 1.67)",
        "AcosX = StrictMath.acos(X)",
        "ExpX = io.deephaven.function.Numeric.exp(X)",
        "ExponentX = StrictMath.getExponent(X)",
    ]
)