Java objects and classes in query strings

The ability to use Java objects and classes in Deephaven query strings is one of its most powerful features. This guide explains how to use Java objects effectively in your queries, even if you have limited Java experience.

Classes and objects in Java

Java is an object-oriented programming language where classes serve as blueprints for creating objects. Unlike Python, where everything is an object, Java distinguishes between primitive types and objects:

  1. Primitive types: Basic data types like int, double, and boolean that are not objects.
  2. Objects: Instances of classes that bundle data and methods together.

For performance reasons, Deephaven tables primarily use primitive types for numeric columns, but many operations require object types.

The root Java object

All objects in Java inherit from the java.lang.Object class. Common Java objects used in Deephaven queries include:

Variables

Java classes can have two types of variables:

  1. Static variables (class variables): Belong to the class itself, not to instances. They are shared across all instances of the class.
  2. Instance variables: Belong to individual object instances created from the class.

In query strings, you access static variables using the class name, while instance variables require an object instance. Unlike Python, Java static variables are accessed using the class name rather than an instance. The following example demonstrates accessing both static and instance variables:

from deephaven import empty_table

source = empty_table(1).update(
    [
        "StaticVariable = Integer.MAX_VALUE",
        "Instance = new int[]{1,2,3}",
        "InstanceVariable = Instance.length",
    ]
)
source_meta = source.meta_table

Methods

Java classes can have three types of methods:

  1. Static methods: Called on the class itself, not on instances
  2. Instance methods: Called on object instances
  3. Constructor methods: Special methods used to create new instances with the new keyword

All three are supported in query strings.

The following example demonstrates all three method types by calling static methods, creating instances with constructors, and calling instance methods:

from deephaven import empty_table
from deephaven import query_library

# Import Java classes
query_library.import_class("java.util.UUID")

source = empty_table(1).update(
    [
        "RandomValueStaticMethod = Math.random()",
        "MaxValueStaticMethod = Math.max(10, 20)",
        "MyUUIDConstructorMethod = new UUID(123456789, 987654321)",
        "UUIDStringInstanceMethod = MyUUIDConstructorMethod.toString()",
    ]
)
source_meta = source.meta_table

Built-in query language methods

The Deephaven Query Language (DQL) has a large number of built-in functions that take Java objects as input.

For example, java.time.Instant and java.time.Duration are common in tables. Many methods in io.deephaven.time.DateTimeUtils (built into the query language by default) accept these object types as input.

The following example demonstrates several built-in methods that work with Java objects in query strings:

from deephaven import empty_table

source = empty_table(10).update(
    [
        "Timestamp = '2025-09-01T09:30:00 ET' + ii * MINUTE",
        "InstantMinusDuration = minus(Timestamp, 'PT5s')",
        "InstantPlusDuration = plus(Timestamp, 'PT10s')",
        "UpperBin = upperBin(Timestamp, 'PT15m')",
        "LowerBin = lowerBin(Timestamp, 'PT8m')",
    ]
)
source_meta = source.meta_table