Casting

Casting changes a value from one data type to another. This guide shows how to use type casts in query strings to control column types. It covers common numeric and string conversions, then casts on values from Python variables, functions, and classes.

In tables, casting gives a column the data type that later operations need. Casting to a Java primitive type also keeps values in compact primitive columns instead of PyObject columns, which use more memory and are slower to work with.

For more information on why casting is important in Python queries, see:

Type casts

A type cast is an expression that converts a value from one data type to another. In Python, you convert types by calling the target type:

In Deephaven, type casts in query strings convert a value or column to another data type. They use Java syntax and follow these rules:

  • Between primitives: a cast between two numeric primitive types widens or narrows the value:
    • Widening, such as (long) on an int, keeps the value.
    • Narrowing, such as (int) on a double, can lose information. (int) drops a double's fractional part.
    • A value outside the target type's range wraps or clamps. A double outside the float range becomes infinity.
    • A result that equals the target type's null constant reads as null. For byte, that constant is -128.
  • Boxed to primitive: a boxed type is a Java object that wraps a primitive value, such as java.lang.Double. A cast from a boxed type to a primitive type works only for the matching primitive type or a wider one.
  • Other objects to primitive: a cast from any other object type, such as java.lang.Object, to a numeric primitive type other than char converts the value with the matching java.lang.Number method, such as intValue. It works whenever the value is a number, even where a plain Java cast would fail. A cast from a PyObject follows the From a PyObject rule instead.
  • To an object type: a cast to an object type, such as (String), is a plain Java cast. It sets the column type. It works only when the value is already an instance of that type, or when it boxes a primitive into its own boxed type or a supertype, such as (Integer) or (Object) on an int. (String) is short for (java.lang.String).
  • From a PyObject: a cast from a PyObject to any primitive type, or to String or Boolean, converts the value through Python. Python None becomes the target type's null value, except for boolean, where it raises an error.
  • Null safety: casts to primitive types other than boolean are null-safe. A null value becomes the null constant of the target type.

For more casting examples, see the casting reference.

Common casting scenarios

Numeric conversions

The following query applies a numeric cast to each column:

  • ByteVal: (byte)128 overflows to -128. That value is the byte null constant, so ByteVal reads as null.
  • ShortVal: (short)32767 is the largest short value, so it fits and is unchanged.
  • IntVal: (int)3.99 truncates to 3.
  • LongVal and DoubleVal: (long) and (double) widen the int column IntVal.
  • FloatVal: (float) rounds a double literal to float precision.

The source_meta table, from meta_table, lists each column's resulting type:

String conversions

A Java cast can't convert between strings and numbers, so call a conversion function instead. parseInt parses a string as an int, and Integer.toString formats an int as a string:

Casts with Python objects

How you cast a value from Python depends on where it comes from: a Python variable, a Python function, or a method of a Python class. The following sections cover each.

Python variables

Python int and float variables reach the query string as boxed Java objects, such as java.lang.Byte or java.lang.Double. The Boxed to primitive rule under Type casts decides which casts work on them.

NumPy integer scalars, such as numpy.int64, arrive as PyObjects instead. A numeric cast on one converts the value through Python, as the From a PyObject rule under Type casts describes.

The following query creates two columns from a Python variable. A Python int becomes the smallest Java integer type that holds its value, so a = 1 arrives as a java.lang.Byte:

  • ByteA uses the variable directly, so it is a byte column.
  • IntA casts the variable to a Java primitive int. The cast works because int is wider than byte.

A cast fails when the target primitive is narrower than the boxed type. For example, a Python float becomes a java.lang.Double, which can't be cast directly to float. The following query fails with an error:

The error message reads:

To get a float column, unbox the value to double first, then narrow it: (float)(double)a. The following query works:

Python functions

When a query string calls a Python function, Deephaven sets the column type from the function's return type hint. A function whose hint maps to a Java type listed in Data types needs no cast. Use a type cast when the function has no return type hint or its hint has no Java mapping, such as -> dict.

Without a return type hint or a cast, the result column isn't typed. For example, if f has no return type hint, f(X) gives a PyObject column, and f(X + 1) gives a java.lang.Object column.

The function random_symbol in the following example has no return type hint, so a type cast converts its return value to a java.lang.String:

Python classes

Unlike Python functions, methods of Python classes called in query strings do not use type hints to set the column type. Instead, a method call produces a java.lang.Object column, so use a type cast when you need a specific column type for its result. The Other objects to primitive rule under Type casts makes a numeric cast such as (int) work on that Object.

The following example casts the results of a class method (change_value), a static method (multiply_modulo), and an instance method (plus_modulo):

Column Q has no cast, so source_meta shows its type as java.lang.Object. The casts give X, Y, and Z the int type.