Skip to content

Predicates

col() and lit() build the conditions a ColRule or a Check carries. Unlike a raw pl.Expr, a predicate built this way survives a round trip through a spec file — see Specs as files.

col

col

col(name: str) -> Col

A reference to a column, the starting point of every predicate.

Exactly the column named name: unlike pl.col, col("*") is the column named *, not every column, and col("^id$") is not a regular expression.

Examples:

>>> pred = (col("total") > 0) & col("status").is_in(["NEW", "PAID"])
>>> pred
(col('total') > 0) & (col('status').is_in(['NEW', 'PAID']))
>>> frame = pl.DataFrame({"total": [5, -1], "status": ["NEW", "NEW"]})
>>> frame.filter(pred.to_expr())["total"].to_list()
[5]

lit

lit

lit(value: Any) -> Pred

An explicit literal. Scalars beside an operator are wrapped automatically.

Examples:

>>> col("total") > lit(100)
col('total') > 100

Pred

Pred dataclass

Pred()

Base class of every predicate node. Build one with col().

Examples:

>>> pred = col("total").is_between(0, 100)
>>> isinstance(pred, Pred), pred
(True, col('total').is_between(0, 100))
>>> Check(pred, name="in_range").name
'in_range'

to_expr

to_expr() -> Expr

This predicate as the Polars expression that evaluates it.

to_data

to_data() -> Any

This predicate as plain data, for writing to a spec file.

to_source

to_source() -> str

This predicate as the col(...) Python that would rebuild it.

rename

rename(mapping: Mapping[str, str]) -> Pred

The same predicate with its columns renamed by mapping.

Derived, so a node cannot be added that silently fails to rename -- which would leave a rule pointing at a column that no longer exists and only surface much later, as a spec failing its own validation.

equals

equals(other: object) -> bool

Structural equality, since == builds a predicate.

is_in

is_in(values: Sequence[Any]) -> IsIn

A predicate true where this value is one of values.

is_null

is_null() -> IsNull

A predicate true where this value is null.

is_not_null

is_not_null() -> Not

A predicate true where this value is present.

is_between

is_between(lower: Any, upper: Any) -> Between

A predicate true where this value falls within [lower, upper].