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:

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

SymbolNameDescription
+AdditionAdds values. If either operand is a String, concatenates the operands as strings.
-SubtractionSubtracts the right value from the left value.
-NegationNegates a single value, as in -A.
*MultiplicationMultiplies the left and right values.
/DivisionDivides the left value by the right value. Dividing two integer values returns a double.
%ModulusDivides the left value by the right value and returns the remainder.

Access operators

SymbolNameDescription
_UnderscoreAppended 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.
[]IndexReads an array element by position, as in A_[i - 2]. For a column array such as A_, a position outside the column returns null.
.DotAccesses a field or method of an object, class, or package, as in obj.compute(A).

Assignment operators

SymbolNameDescription
=AssignmentIn 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

SymbolNameDescription
==Equal toReturns true if the two values are equal. Two null values are equal.
!=Not equal toReturns true if the two values are not equal.
>Greater thanReturns true if the left value is greater than the right value.
>=Greater than or equalReturns true if the left value is greater than or equal to the right value.
<Less thanReturns true if the left value is less than the right value.
<=Less than or equalReturns 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:

  • less_than_ten keeps the null row and the 5.0 row. The null row passes A < 10 because null sorts first, and the NaN row fails it.
  • non_null_less_than_ten adds an isNull check, so it keeps only the 5.0 row.
  • nan_or_ten keeps the NaN row, because set inclusion with in matches NaN.
  • equals_five uses a single = to test for equality and keeps the 5.0 row.

Logical operators

SymbolNameDescription
!Logical NOTInverts 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 XORReturns true if exactly one operand is true.
&&Logical ANDReturns true if both operands are true. Skips the right operand when the left is false.
||Logical ORReturns 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.

SymbolNameDescription
&Bitwise ANDSets each result bit to 1 if both corresponding operand bits are 1, and to 0 otherwise.
|Bitwise ORSets each result bit to 1 if either corresponding operand bit is 1, and to 0 otherwise.
^Bitwise XORSets 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

SymbolNameDescription
(type)CastingCasts from one type to another.
()Function callCalls a function.
?:Ternary conditionalReturns 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, combine the filters with or_, as in where(or_(["X in 2, 4", "Y > 3"])).

See Match filters and String filters for examples.

SymbolNameDescription
inSet inclusionReturns true if the column value matches any of the listed values, as in X in 2, 4, 6.
not inSet exclusionReturns true if the column value matches none of the listed values.
icase in, icase not inCase-insensitive set matchWork like in and not in, but ignore case when matching strings.
includesSubstring matchReturns true if a string column contains the listed substring. With several substrings, works like includes any.
includes anyAny-substring matchReturns true if a string column contains any of the listed substrings.
includes allAll-substring matchReturns 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.