Groovy classes and objects in query strings

Using your own Groovy variables, closures, classes, and objects in Deephaven query strings is one of Deephaven's most powerful features. Using Groovy classes in query strings follows a few basic rules. This guide shows how to make a Groovy class available to query strings and how to use its variables and methods there.

Classes and objects in Groovy

Groovy is an object-oriented programming language. Its design revolves around objects, which bundle data (fields) with the code (methods) that operates on it.

Classes are blueprints for objects. They define the fields and methods of every object created from the class. A member declared static belongs to the class itself, so you can use it without creating an object. Other members are instance members. Each object has its own copy of the instance variables, and instance methods run on a particular object.

Make a Groovy class available to query strings

Query strings can refer by simple name only to the classes, packages, and static members in the query library. Deephaven compiles query strings separately from your Groovy script, so a class your script defines, such as MyClass, isn't in the query library until you add it.

To use the class name in query strings, add the class to the query library of the current execution context with ExecutionContext.getContext().getQueryLibrary().importClass. The MyClass and Calculator examples below call it right after the class definition.

Query strings can use a class's members without the import in two cases:

  • To use an object created from the class, assign it to a top-level script variable without def or a type, such as myObj = new MyClass(2). That puts it in the query scope, so a query string can use the object's public variables and methods. For why def and typed variables don't work, see Groovy variables in query strings.
  • To use a static value, copy it to a top-level script variable the same way, such as staticA = MyClass.a, and use staticA in the query string.

To reuse classes across scripts, keep them out of the console script:

A Groovy import of such a class doesn't reach query strings. Import it with importClass or use its fully qualified name.

Static and instance variables in query strings

Like methods, variables are either static or instance members. In the example below, a is a static variable, so a query string can use it without an object. b is an instance variable, so a query string needs an object to read it.

Because the example imports MyClass into the query library, the query string can read a through the class name. It reads b through the object myObj, which works without the import:

The meta table, sourceMeta, shows that X and Y are int columns, matching the declared types of a and b.

The example declares both variables public. A variable declared without an access modifier, such as int b, is a Groovy property:

  • Groovy makes the field private, so query strings can't read it.
  • Groovy generates a public getter for it, named after the property. The getter for b is getB, and a static property, such as static int a, gets a static getter, getA.

In a query string, call the getter instead: myObj.getB() for an instance property or MyClass.getA() for a static one. The following example calls getB:

Methods in query strings

Like variables, methods are either static or instance members. An instance method runs on one object and can read both its instance variables and the class's static variables. Query strings can call both kinds of methods.

The following code block calls two static methods through the imported class Calculator and an instance method through the instance myObj:

Each column takes its type from the method's declared return type, so the meta table, sourceMeta, shows that X and Z are int columns and Y is a double column.

A method declared with def instead of a return type returns Object. To get a specific column type from such a method, cast its result in the query string.