Data Types¶

The logical types of the elements of an Array. Each logical type is implemented by a variety of Array encodings which describe both a representation-as-bytes as well as how to apply operations on that representation.

Factory Functions¶

vortex.null()¶

Construct the data type for a column containing only the null value.

Return type:: vortex.DType

Examples

A data type permitting only None.

>>> vx.null()
null()

vortex.bool_(*, nullable=False)¶

Construct a Boolean data type.

Parameters:: nullable (bool) – When True, None is a permissible value.
Return type:: vortex.DType

Examples

A data type permitting None, True, and False.

>>> import vortex as vx
>>> vx.bool_(nullable=True)
bool(nullable=True)

A data type permitting just True and False.

>>> vx.bool_()
bool(nullable=False)

vortex.float_(width=64, *, nullable=False)¶

Construct an IEEE 754 binary floating-point data type.

Parameters:

width (Literal[16, 32, 64].) – The bit width determines the range and precision of the floating-point values. If None, 64 is used.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type permitting None as well as IEEE 754 binary16 floating-point values. Values larger than 65,520 or less than -65,520 will respectively round to positive and negative infinity.

>>> import vortex as vx
>>> vx.float_(16, nullable=False)
float(16, nullable=False)

vortex.int_(width=64, *, nullable=False)¶

Construct a signed integral data type.

Parameters:

width (Literal[8, 16, 32, 64].) – The bit width determines the span of valid values. If None, 64 is used.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type permitting None and the integers from -128 to 127, inclusive:

>>> import vortex as vx
>>> vx.int_(8, nullable=True)
int(8, nullable=True)

A data type permitting just the integers from -2,147,483,648 to 2,147,483,647, inclusive:

>>> vx.int_(32)
int(32, nullable=False)

vortex.uint(width=64, *, nullable=False)¶

Construct an unsigned integral data type.

Parameters:

width (Literal[8, 16, 32, 64].) – The bit width determines the span of valid values. If None, 64 is used.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type permitting None and the integers from 0 to 255, inclusive:

>>> import vortex as vx
>>> vx.uint(8, nullable=True)
uint(8, nullable=True)

A data type permitting just the integers from 0 to 4,294,967,296 inclusive:

>>> vx.uint(32, nullable=False)
uint(32, nullable=False)

vortex.decimal(*, precision=10, scale=0, nullable=False)¶

Construct a decimal data type.

Parameters:

precision (int) – The number of significant digits representable by an instance of this type.
scale (int) – The number of digits after the decimal point that are represented. If negative, the number of trailing zeros in the whole number portion.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type permitting None and the integers from -128 to 127, inclusive:

>>> import vortex as vx
>>> vx.decimal(precision=13, scale=2, nullable=True)
decimal(precision=13, scale=2, nullable=True)

A data type representing fixed-width decimal numbers with precision significant figures and scale digits after the decimal point. If scale is a negative value, then it is taken to be the number of trailing zeros before the decimal point.

>>> vx.decimal(precision = 10, scale = 3)
decimal(precision=10, scale=3, nullable=False)

vortex.utf8(*, nullable=False)¶

Construct a UTF-8-encoded string data type.

Parameters:: nullable (bool) – When True, None is a permissible value.
Return type:: vortex.DType

Examples

A data type permitting any UTF-8-encoded string, such as "Hello World", but not permitting None.

>>> import vortex as vx
>>> vx.utf8(nullable=False)
utf8(nullable=False)

vortex.binary(*, nullable=False)¶

Construct a binary data type.

Parameters:: nullable (bool) – When True, None is a permissible value.
Return type:: vortex.DType

Examples

A data type permitting any string of bytes but not permitting None.

>>> import vortex as vx
>>> vx.binary(nullable=False)
binary(nullable=False)

vortex.struct(fields=None, *, nullable=False)¶

Construct a struct data type.

Parameters:

fields (dict) – A mapping from field names to data types.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type permitting a struct with two fields, "name" and "age", where "name" is a UTF-8-encoded string and "age" is a 32-bit signed integer:

>>> import vortex as vx
>>> vx.struct({"name": vx.utf8(), "age": vx.int_(32)})
struct({"name": utf8(nullable=False), "age": int(32, nullable=False)}, nullable=False)

vortex.list_(element, *, nullable=False)¶

Construct a list data type.

Parameters:

element (DType) – The type of the list element.
nullable (bool) – When True, None is a permissible value (note that this is the nullability of the lists, not the inner elements).

Return type:

vortex.DType

Examples

A data type permitting a list of 32-bit signed integers, but not permitting None.

>>> import vortex as vx
>>> vx.list_(vx.int_(32), nullable=False)
list(int(32, nullable=False), nullable=False)

vortex.fixed_size_list(element, size, *, nullable=False)¶

Construct a fixed-size list data type.

Parameters:

element (DType) – The element type of the fixed-size list.
size (int) – The size of each list scalar.
nullable (bool) – When True, None is a permissible value (note that this is the nullability of the fixed-size lists, not the inner elements).

Return type:

DType

Examples

Create a fixed-size list of 3 integers:

>>> import vortex as vx
>>> vx.fixed_size_list(vx.int_(32), 3, nullable=False)
fixed_size_list(int(32, nullable=False), 3, nullable=False)

vortex.date(unit, *, nullable=False)¶

Construct a date data type.

Parameters:

unit (str) – The time unit for the date. Must be one of 'ms' or 'days'.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type representing dates as days since the UNIX epoch.

>>> import vortex as vx
>>> vx.date("days")
ext("vortex.date", int(32, nullable=False), days)

vortex.time(unit, *, nullable=False)¶

Construct a time-of-day data type.

Parameters:

unit (str) – The time unit for the time. Must be one of 's', 'ms', 'us', or 'ns'.
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A data type representing time of day in microseconds.

>>> import vortex as vx
>>> vx.time("us")
ext("vortex.time", int(64, nullable=False), µs)

vortex.timestamp(unit, *, tz=None, nullable=False)¶

Construct a timestamp data type.

Parameters:

unit (str) – The time unit for the timestamp. Must be one of 's', 'ms', 'us', or 'ns'.
tz (str or None) – An optional timezone string (e.g. "UTC").
nullable (bool) – When True, None is a permissible value.

Return type:

vortex.DType

Examples

A non-nullable timestamp in microseconds with no timezone.

>>> import vortex as vx
>>> vx.timestamp("us")
ext("vortex.timestamp", int(64, nullable=False), µs)

A nullable timestamp in seconds with a UTC timezone.

>>> vx.timestamp("s", tz="UTC", nullable=True)
ext("vortex.timestamp", int(64, nullable=True), s, tz=UTC)

Base Class¶

Do not instantiate these classes directly. Instead, call one of the factory functions above.

class vortex.DType¶

Base class for all Vortex data types.

classmethod from_arrow(arrow_dtype, *, non_nullable=False)¶: Construct a Vortex data type from an Arrow data type.

is_nullable()¶: Return whether this data type allows null values.

DType Classes¶

class vortex.NullDType¶: Concrete class for null dtypes.

class vortex.BoolDType¶: Concrete class for boolean dtypes.

class vortex.PrimitiveDType¶

Concrete class for primitive dtypes.

ptype¶: The PType of the primitive dtype.

class vortex.Utf8DType¶: Concrete class for utf8 dtypes.

class vortex.BinaryDType¶: Concrete class for utf8 dtypes.

class vortex.StructDType¶

Concrete class for struct dtypes.

fields()¶: Returns the field DTypes of the struct.

names()¶: Returns the names of the struct fields.

class vortex.ListDType¶: Concrete class for list dtypes.

class vortex.ExtensionDType¶: Concrete class for extension dtypes.

Primitive Types¶

class vortex.PType¶: Enum for primitive types.