Operators
An operator is a symbol, like + or -, that tells a program to perform a specific action on values or variables. You use operators inside query strings, written in the Deephaven Query Language (DQL), to build filters and formulas. Deephaven provides access to most of Java's operators.
Filters and formulas work on real-time tables as well as static ones, so the results of your operators update as the data changes.
The following code block uses a variety of operators to create new columns of values.
A = i uses the assignment operator to fill A with each row's position, read from the special variable i. Each column after A demonstrates one or more operators:
B,C, andDuse the arithmetic operators*,/, and%. Dividing two integers returns adouble, soCis adoublecolumn.Euses a cast to convertCto anint.Fuses the underscore and index operators to read the value ofAtwo rows earlier. In the first two rows, there is no earlier row to read, soFisnull.GandHuse the dot operator to call methods ofobj.GcallsgetA, the getter that Groovy generates for theaproperty, because a query string can't read the property's private field directly.Hcallscompute. See Groovy classes and objects in query strings for more information.Iuses the function call operator to call the built-insqrtfunction.
The following example uses the comparison operators >, >=, <, and <= in filters to keep only the matching rows of the source table.
Available operators
The subsections below group the operators available in query strings by category.
Arithmetic operators
| Symbol | Name | Description |
|---|---|---|
+ | Addition | Adds values. If either operand is a String, concatenates the operands as strings. |
- | Subtraction | Subtracts the right value from the left value. |
- | Negation | Negates a single value, as in -A. |
* | Multiplication | Multiplies the left and right values. |
/ | Division | Divides the left value by the right value. Dividing two integer values returns a double. |
% | Modulus | Divides the left value by the right value and returns the remainder. |
Access operators
| Symbol | Name | Description |
|---|---|---|
_ | Underscore | Appended to a column name, as in A_, accesses the whole column as an array. This operator is Deephaven-specific and is not part of Java. |
[] | Index | Reads an array element by position, as in A_[i - 2]. For a column array such as A_, a position outside the column returns null. |
. | Dot | Accesses a field or method of an object, class, or package, as in obj.getA(). |
Assignment operators
| Symbol | Name | Description |
|---|---|---|
= | Assignment | In a formula, the first = assigns the expression on the right to the column named on the left. Everywhere else in a query string, = tests for equality. See Comparison operators. |
Comparison operators
| Symbol | Name | Description |
|---|---|---|
== | Equal to | Returns true if the two values are equal. Two null values are equal. |
!= | Not equal to | Returns true if the two values are not equal. |
> | Greater than | Returns true if the left value is greater than the right value. |
>= | Greater than or equal | Returns true if the left value is greater than or equal to the right value. |
< | Less than | Returns true if the left value is less than the right value. |
<= | Less than or equal | Returns true if the left value is less than or equal to the right value. |
A single = also tests for equality, the same as ==. This applies everywhere except the first = in a formula, which assigns the column. For example, the filter Value = 3 keeps rows where Value is 3, and A = 3 && B = 5 keeps rows where A is 3 and B is 5. Prefer ==, which makes the intent clear.
Note
Deephaven orders null before every non-null value, and comparisons follow that order. When A is null, A < 10 and A <= 10 are true. To exclude nulls, add an explicit check with isNull, as in !isNull(A) && A < 10. See Null, NaN, and infinity values.
Note
Comparisons with NaN follow IEEE 754 rules. When either operand is NaN, ==, <, <=, >, and >= return false, and != returns true. Set inclusion with in is the exception: the filter A in NaN, 10.0 keeps NaN rows. To test for NaN explicitly, use isNaN, as in isNaN(A) || A < 10.0.
To see these rules in action, let's filter a column that holds a null, an ordinary value, and a NaN:
lessThanTenkeeps the null row and the5.0row. The null row passesA < 10becausenullsorts first, and theNaNrow fails it.nonNullLessThanTenadds anisNullcheck, so it keeps only the5.0row.nanOrTenkeeps theNaNrow, because set inclusion withinmatchesNaN.equalsFiveuses a single=to test for equality and keeps the5.0row.
Logical operators
| Symbol | Name | Description |
|---|---|---|
! | Logical NOT | Inverts the value of a boolean. |
& | Logical AND (non-short-circuit) | Returns true if both operands are true. Always evaluates both operands. |
| | Logical OR (non-short-circuit) | Returns true if either operand is true. Always evaluates both operands. |
^ | Logical XOR | Returns true if exactly one operand is true. |
&& | Logical AND | Returns true if both operands are true. Skips the right operand when the left is false. |
|| | Logical OR | Returns true if either operand is true. Skips the right operand when the left is true. |
See Combine filters for examples that combine filter conditions with && and ||.
Bitwise operators
With integer operands (byte, short, char, int, or long), &, |, and ^ operate on the individual bits of each value. With boolean operands, they are the logical operators described above.
| Symbol | Name | Description |
|---|---|---|
& | Bitwise AND | Sets each result bit to 1 if both corresponding operand bits are 1, and to 0 otherwise. |
| | Bitwise OR | Sets each result bit to 1 if either corresponding operand bit is 1, and to 0 otherwise. |
^ | Bitwise XOR | Sets each result bit to 1 if the corresponding operand bits differ, and to 0 otherwise. |
Query strings don't support the bitwise complement (~) or shift (<<, >>, >>>) operators.
Other Java operators
| Symbol | Name | Description |
|---|---|---|
(type) | Casting | Casts from one type to another. |
() | Function call | Calls a function. |
?: | Ternary conditional | Returns one of two values depending on the value of a boolean expression. |
Query strings don't support these Java operators:
instanceof- Unary plus, as in
+A - Increment (
++) and decrement (--) - Compound assignment, such as
+=
Filter-only operators
These Deephaven-specific operators work only in filter strings, such as those passed to where. Three rules apply to them:
- Formulas can't use them.
- The left side of each must be a column name.
- Each one must be the whole filter string, so you can't combine it with other conditions using
&&or||.
To combine one with another condition, pass the conditions as separate filters, as in where("X in 2, 4", "Y > 3"). The result keeps only rows that match every filter. To keep rows that match either condition instead, import io.deephaven.api.filter.Filter and combine the filters with Filter.or, as in where(Filter.or(Filter.from("X in 2, 4", "Y > 3"))).
See Match filters and String filters for examples.
| Symbol | Name | Description |
|---|---|---|
in | Set inclusion | Returns true if the column value matches any of the listed values, as in X in 2, 4, 6. |
not in | Set exclusion | Returns true if the column value matches none of the listed values. |
icase in, icase not in | Case-insensitive set match | Work like in and not in, but ignore case when matching strings. |
includes | Substring match | Returns true if a string column contains the listed substring. With several substrings, works like includes any. |
includes any | Any-substring match | Returns true if a string column contains any of the listed substrings. |
includes all | All-substring match | Returns true if a string column contains all of the listed substrings. |
Prefix includes with icase to ignore case, not to invert the match, or both, as in icase not includes.
Related documentation
- Query strings
- Filters
- Formulas
- Filter table data
- Select and create columns
- Groovy classes and objects in query strings
- Arrays
- Arrays reference
- Casting
- Casting reference
- Use the ternary conditional operator in query strings
- Null, NaN, and infinity values
- Query language built-in constants
emptyTablenewTableintColdoubleColupdatewhere- Special variables and constants
isNullisNaNsqrt=!=innot inicase inicase not inTableToolsJavadocTableOperationsJavadocFilterJavadoc