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 anint, keeps the value. - Narrowing, such as
(int)on adouble, can lose information.(int)drops adouble's fractional part. - A value outside the target type's range wraps or clamps. A
doubleoutside thefloatrange becomes infinity. - A result that equals the target type's null constant reads as null. For
byte, that constant is-128.
- Widening, such as
- 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 thancharconverts the value with the matchingjava.lang.Numbermethod, such asintValue. It works whenever the value is a number, even where a plain Java cast would fail. A cast from aPyObjectfollows 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 anint.(String)is short for(java.lang.String). - From a PyObject: a cast from a
PyObjectto any primitive type, or toStringorBoolean, converts the value through Python. PythonNonebecomes the target type's null value, except forboolean, where it raises an error. - Null safety: casts to primitive types other than
booleanare 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)128overflows to-128. That value is thebytenull constant, soByteValreads as null.ShortVal:(short)32767is the largestshortvalue, so it fits and is unchanged.IntVal:(int)3.99truncates to3.LongValandDoubleVal:(long)and(double)widen theintcolumnIntVal.FloatVal:(float)rounds adoubleliteral tofloatprecision.
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:
ByteAuses the variable directly, so it is abytecolumn.IntAcasts the variable to a Java primitiveint. The cast works becauseintis wider thanbyte.
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.
Related documentation
- The Python-Java boundary
- Access metadata
- Data types
- Query string overview
- Query scope
- Python variables in query strings
- Python functions in query strings
- Python classes in query strings
- PyObjects in tables
- Casting
- Nulls
empty_tablemeta_table- Parse functions
updateempty_tablePydocmeta_tablePydocupdatePydoc