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, leveraging Groovy's seamless Java interoperability.

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. The following example demonstrates accessing both static and instance variables:

source = emptyTable(1).update(
    "StaticVariable = Integer.MAX_VALUE",
    "Instance = new int[]{1,2,3}",
    "InstanceVariable = Instance.length",
)
sourceMeta = source.meta()

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:

source = emptyTable(1).update(
    "RandomValueStaticMethod = Math.random()",
    "MaxValueStaticMethod = Math.max(10, 20)",
    "MyUUIDConstructorMethod = new java.util.UUID(123456789, 987654321)",
    "UUIDStringInstanceMethod = MyUUIDConstructorMethod.toString()",
)
sourceMeta = source.meta()

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:

source = emptyTable(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')",
)
sourceMeta = source.meta()

Groovy's Java interoperability

One of Groovy's greatest strengths is its seamless interoperability with Java. In Groovy query strings, you can:

  • Use any Java class without imports (for classes in java.lang and other common packages)
  • Access Java static methods and variables directly
  • Create Java objects using the new keyword
  • Call Java instance methods on objects

This makes working with Java objects in Groovy query strings very natural and straightforward.