Python classes and objects in query strings
Using your own Python variables, functions, classes, and objects in Deephaven query strings is one of Deephaven's most powerful features. This guide shows how to use class variables, instance variables, and class, static, and instance methods, and how to give the resulting columns the right data types.
Caution
Python classes and objects in query strings have performance and memory implications. Python objects live outside the Java heap, so they can significantly increase the process's resident memory. For performance-critical or high-throughput queries, consider using built-in query language functions instead.
Class and instance variables in query strings
A class is a blueprint for objects: it defines the data and behavior that each object created from it has. Classes can have class variables, which belong to the class itself, and instance variables, which belong to each object.
In the example below, a is a class variable and b is an instance variable. You can use a without an instance of the class, but b requires one. In the query string, access a through the class MyClass and b through the instance my_class:
In the example above, source_meta shows that the X and Y columns are of type org.jpy.PyObject. The engine reads class and instance variables from the Python object at run time, so it can't tell their types when it compiles the query string. A type annotation such as a: int = 1 doesn't change this.
Top-level Python variables behave differently, because Deephaven sets their column types from their values. To give a class or instance variable a specific column type, use a type cast.
The following example adds type casts that make X an int column and Y a double column:
In source_meta, X is now an int column and Y, which holds the instance value 2.1, is a double column.
Methods in query strings
In Python, classes can have three types of methods:
- Class methods: They use the
@classmethoddecorator and takeclsas the first parameter. They operate on the class itself and can access class variables. - Static methods: They use the
@staticmethoddecorator and take neitherselfnorcls, so they receive no implicit reference to the instance or class. - Instance methods: They use no decorator and take
selfas the first parameter. They require an instance of the class and can access instance variables.
Query strings support all three.
The following example calls a class method, a static method, and an instance method in a query string. It calls the instance method on my_class, an instance of MyClass. Deephaven ignores type hints on methods called through a class or object, so the example uses type casts to give each column a Java primitive type:
In source, scaled_value multiplies the class variable my_value, which is 3, by 5, so X is 15. Y and Z use X as the modulus, giving 11 and 6.
In source_meta, the casts make X, Y, and Z columns of type int. Without a cast, a method call produces a java.lang.Object column.
Related documentation
- Python-Java boundary
- Query strings overview
- Query scope
- Query language built-in constants
- Built-in query language variables
- Built-in query language functions
- Formulas in query strings
- Python variables in query strings
- Python functions in query strings
- PyObjects in tables
- Casting
- Data types in Deephaven and Python
empty_tablemeta_tableupdateempty_tablePydocmeta_tablePydocupdatePydoc