Expressions¶

Vortex expressions represent simple filtering conditions on the rows of a Vortex array. For example, the following expression represents the set of rows for which the age column lies between 23 and 55:

>>> import vortex.expr
>>> age = vortex.expr.column("age")
>>> (23 > age) & (age < 55)

`column`	Create an expression that refers to a column by its name.
`Expr`	An expression describes how to filter rows when reading an array from a file.

vortex.expr.column(name)¶

Create an expression that refers to a column by its name.

Parameters:: name (str) – The name of the column.
Return type:: vortex.Expr

Examples

>>> import vortex.expr as ve
>>> ve.column("age")
<vortex.Expr object at ...>

See also

Use vortex.expr.Expr.__getitem__() to retrieve a field of a struct array.

vortex.expr.not_(child)¶

Negate a Boolean expression.

Parameters:: child (Any) – A boolean expression.
Return type:: vortex.Expr

Examples

>>> import vortex.expr as ve
>>> import vortex as vx
>>> ve.not_(ve.literal(vx.int_(), 42) == ve.literal(vx.int_(), 42))
<vortex.Expr object at ...>

vortex.expr.and_(left, right)¶

True if both arguments are true.

Parameters:

left (Expr) – A boolean expression.
right (Expr) – A boolean expression.

Return type:

vortex.Expr

Examples

>>> import vortex.expr as ve
>>> import vortex as vx
>>> ve.and_(ve.literal(vx.bool_(), True), ve.literal(vx.bool_(), True))
<vortex.Expr object at ...>

vortex.expr.root()¶

Create an expression that refers to the identity scope.

That is, it returns the full input that the extension is run against.

Return type:: vortex.Expr

Examples

>>> import vortex.expr as ve
>>> ve.root()
<vortex.Expr object at ...>

vortex.expr.literal(dtype, value)¶

Create an expression that represents a literal value.

Parameters:

dtype (vortex.DType) – The data type of the literal value.
value (Any) – The literal value.

Return type:

vortex.Expr

Examples

>>> import vortex.expr as ve
>>> ve.literal(vx.int_(), 42)
<vortex.Expr object at ...>

class vortex.expr.Expr¶

An expression describes how to filter rows when reading an array from a file.

See also

column()

__getitem__(name, /)¶

Extract a field of a struct array.

Parameters:

name (str) – The name of the field.

Return type:

vortex.Expr

Examples

>>> import vortex as vx
>>> import vortex.expr as ve
>>> import pyarrow as pa
>>>
>>> array = pa.array([
...     {"x": 1, "y": {"yy": "a"}},
...     {"x": 2, "y": {"yy": "b"}},
... ])
>>>
>>> vx.io.write(vx.array(array), '/tmp/foo.vortex')
>>> (vx.file.open('/tmp/foo.vortex')
...    .scan(expr=vx.expr.column("y")["yy"] == "a")
...    .read_all()
...    .to_pylist()
... )
[{'x': 1, 'y': {'yy': 'a'}}]

evaluate(array)¶

Evaluate this expression on an in-memory array.

Examples

Extract one column from a Vortex array:

>>> import vortex.expr as ve
>>> import vortex as vx
>>> array = ve.column("a").evaluate(vx.array([{"a": 0, "b": "hello"}, {"a": 1, "b": "goodbye"}]))
>>> array.to_arrow_array()
<pyarrow.lib.Int64Array object at ...>
[
 0,
 1
]

Evaluating an expression on an Arrow array or table implicitly converts it to a Vortex array:

>>> import pyarrow as pa
>>> array = ve.column("a").evaluate(pa.Table.from_arrays(
...     [[0, 1, 2, 3]],
...     names=['a'],
... ))
>>> array
<vortex.PrimitiveArray object at ...>