Scalars¶

A scalar is a single atomic value like the integer 1, the string "hello", or the structure {"age": 55, "name": "Angela"}. The Array.scalar_at() method returns a native Python value when the cost of doing so is small. However, for larger values like binary data, UTF-8 strings, variable-length lists, and structures, Vortex returns a zero-copy view of the Array data. The into_python method of each view will copy the scalar into a native Python value.

Factory Function¶

vortex.scalar(value, *, dtype=None)¶

Construct a Vortex scalar from a Python value.

Parameters:

value (object) – The value to convert. Supported types are None, bool, int, float, str, bytes, list, dict (as a struct), decimal.Decimal, datetime.date, datetime.datetime, datetime.time, uuid.UUID, and vortex.Scalar.
dtype (vortex.DType, optional) – The data type of the result. When given, it also guides the conversion: the unit of a date, time or timestamp type, the scale of a decimal type, and the element and field types of list and struct types. Without it, int becomes a 64-bit integer, float a 64-bit float, decimal.Decimal a decimal with the value’s own precision and scale, dates use days, and times and timestamps use microseconds.

Return type:

vortex.Scalar

Raises:

ValueError – If the value cannot be represented exactly, for example a decimal or timestamp that would lose precision in the requested scale or unit, a non-finite decimal, or a timezone that has no IANA name.

Notes

Comparisons in expressions require both sides to have the same type, so a literal compared against a column should match the column’s type, for example vx.scalar(value, dtype=vx.timestamp("ns")) for a nanosecond timestamp column.

Examples

>>> import datetime
>>> import vortex as vx
>>> vx.scalar(datetime.date(1970, 1, 2)).as_py()
1
>>> vx.scalar(datetime.time(0, 0, 1), dtype=vx.time("ms")).as_py()
1000

Base Class¶

class vortex.Scalar¶

Base class for Vortex scalar types.

as_py()¶: Return the scalar value as a Python object.

dtype¶: Return the DType of the scalar.

Scalar Classes¶

class vortex.NullScalar¶

class vortex.BoolScalar¶: Concrete class for boolean scalars.

class vortex.PrimitiveScalar¶: Concrete class for primitive scalars.

class vortex.Utf8Scalar¶: Concrete class for utf8 scalars.

class vortex.BinaryScalar¶: Concrete class for binary scalars.

class vortex.StructScalar¶

Concrete class for struct scalars.

field(name)¶: Return the child scalar with the given field name.

class vortex.ListScalar¶

Concrete class for list scalars.

element(idx)¶: Return the child scalar at the given index.

class vortex.ExtensionScalar¶

Concrete class for extension scalars.

storage()¶: Return the underlying storage scalar.