Query language built-in constants

The Deephaven Query Language (DQL) has a large number of built-in constants that you can use in query strings with no imports or setup. This guide covers these groups of built-in constants:

  • Null values.
  • Minimum and maximum allowed values.
  • Infinities.
  • NaNs, or Not a Number values.
  • Lengths of time and time-unit conversion factors.
  • The math constants E and PI.

The constants in this guide use upper snake case, such as NULL_INT, following the Java naming convention for constants. For every constant with its type, see Auto-imported constants.

Query strings also have built-in named colors, such as BLUE, for table formatting. See Auto-imported GUI functions for the list.

Two more built-in fields set how query strings divide BigDecimal and BigInteger values. The Other built-in fields section at the end of this guide describes them.

Note

A Groovy variable with the same name as a built-in constant takes precedence over the built-in. For example, after NULL_INT = 0 at the top level of a script, the query string "X = NULL_INT" uses the Groovy variable, so X is 0, not null. Don't give Groovy variables the names of built-in constants. Query scope explains which Groovy variables a query string can see.

Null constants

Each Java primitive data type except boolean has a constant for its null value. NULL_BOOLEAN is the null value for Boolean columns, and it equals null. The query below shows the primitive null constants and NULL_BOOLEAN:

Each cell holds its column type's null value, which the table displays as an empty cell.

Boxed forms such as NULL_INT_BOXED also exist for the numeric and char types. They hold the same null value as a Java wrapper object, such as Integer, instead of a primitive.

To check for nulls or replace them in a query, see Null, NaN, and infinity values.

Minimum and maximum constants

Every Java primitive type except boolean has constants for its minimum and maximum non-null values. MAX_BYTE, MAX_SHORT, MAX_INT, MAX_LONG, and MIN_CHAR equal Java's limits. The rest differ from Java's limits for one of two reasons:

  • Deephaven reserves one value of each numeric and char type to represent null:
    • MIN_BYTE, MIN_SHORT, MIN_INT, and MIN_LONG are one greater than Java's minimum, because Java's minimum is the null value. For example, MIN_INT is Integer.MIN_VALUE + 1.
    • MAX_CHAR is Character.MAX_VALUE - 1, because Character.MAX_VALUE is NULL_CHAR.
  • Deephaven defines the floating-point minimum and maximum as infinities. MAX_DOUBLE and MAX_FLOAT are positive infinity, and MIN_DOUBLE and MIN_FLOAT are negative infinity.

Because the floating-point minimum and maximum are infinities, Deephaven also provides finite limits:

  • MAX_FINITE_DOUBLE and MAX_FINITE_FLOAT are the largest finite values, Double.MAX_VALUE and Float.MAX_VALUE.
  • MIN_FINITE_DOUBLE and MIN_FINITE_FLOAT are the most negative finite values that aren't null. Deephaven uses -Double.MAX_VALUE and -Float.MAX_VALUE as NULL_DOUBLE and NULL_FLOAT, so each MIN_FINITE_* constant is the next value above its type's null value.
  • MIN_POS_DOUBLE and MIN_POS_FLOAT are the smallest positive values, Double.MIN_VALUE and Float.MIN_VALUE.

The query below uses these constants in query strings:

The table's default number format rounds to four decimal places, so MinPosDouble and MinPosFloat display as 0.0000 even though they are greater than zero. MinChar and MaxChar are unprintable characters, so their cells can look empty even though neither is null.

Infinity constants

Both Java floating-point types, float and double, have positive and negative infinity constants. Each one equals a floating-point limit:

  • POS_INFINITY_FLOAT equals MAX_FLOAT.
  • NEG_INFINITY_FLOAT equals MIN_FLOAT.
  • POS_INFINITY_DOUBLE equals MAX_DOUBLE.
  • NEG_INFINITY_DOUBLE equals MIN_DOUBLE.

The Minimum and maximum constants section above explains why. The query below uses all four infinity constants in query strings:

NaN constants

A NaN (Not a Number) value is a special floating-point value that represents an undefined or unrepresentable value. NaNs only exist for the floating-point types, float and double. The query below uses the NaN constants in query strings:

Date-time constants

Most built-in date-time constants, such as SECOND and DAY, are lengths of time stored as long nanosecond counts, not Duration objects:

  • MICRO: One microsecond in nanoseconds.
  • MILLI: One millisecond in nanoseconds.
  • SECOND: One second in nanoseconds.
  • MINUTE: One minute in nanoseconds.
  • HOUR: One hour in nanoseconds.
  • DAY: One day in nanoseconds.
  • WEEK: One week in nanoseconds.
  • YEAR_365: One year in nanoseconds (365 days).
  • YEAR_AVG: One year in nanoseconds (average, 365.2425 days).

These constants are fixed lengths of time that don't account for calendar adjustments. DAY is always 24 hours, even across a daylight saving time change. YEAR_365 is always 365 days, even in a leap year.

The conversion factors are double values that turn a nanosecond count into another unit. Multiply a count by a factor to convert it. For example, multiplying by DAYS_PER_NANO converts nanoseconds to days. The conversion factors are:

  • SECONDS_PER_NANO: The number of seconds per nanosecond.
  • MINUTES_PER_NANO: The number of minutes per nanosecond.
  • HOURS_PER_NANO: The number of hours per nanosecond.
  • DAYS_PER_NANO: The number of days per nanosecond.
  • YEARS_PER_NANO_365: The number of years per nanosecond (365 days).
  • YEARS_PER_NANO_AVG: The number of years per nanosecond (average, 365.2425 days).

One date-time constant is neither a length of time nor a conversion factor: ZERO_LENGTH_INSTANT_ARRAY is a zero-length Instant array.

The query below adds multiples of the duration constants to a timestamp. The last two columns use diffNanos and conversion factors to express elapsed time in days and in average years:

ElapsedDays grows by 1/24 of a day per row. ElapsedAvgYears falls slightly behind ii, because a 365-day year is shorter than an average year of 365.2425 days.

Math constants

Deephaven has only two built-in math constants:

  • E: The base of the natural logarithm, approximately 2.718281828459045.
  • PI: The ratio of a circle's circumference to its diameter, approximately 3.141592653589793.

The query below uses PI to compute the circumference and area of circles, and uses log to confirm that the natural logarithm of E is 1:

Other built-in fields

Two more built-in fields control how query strings divide BigDecimal and BigInteger values. They are settings, not data values:

  • DEFAULT_SCALE: The minimum scale of a division result. Scale is the number of digits after the decimal point. The default is 8. To change it, set the QueryLanguageFunctionUtils.defaultScale configuration property.
  • ROUNDING_MODE: The rounding mode for division, HALF_UP.