Skip to content

Predicates

altar.predicates builds the portable three-valued expressions that bindings use for prioritization rules and filters. Write a prioritization rule explains them.

Stable, except SqlDialect, which is provisional. See Provisional names.

predicates

Stable predicate DSL shared by model and evidence-source bindings.

A predicate built here has matching Python and SQL interpretations. Binding authors should use this façade instead of the implementation module under :mod:altar.plugins.

SqlDialect names the SQL dialect Predicate.to_sql renders to. It is provisional and listed in __provisional__.

Abs dataclass

Abs(operand: Term)

Bases: Term

The absolute value of another term.

And dataclass

And(*operands: Predicate)

Bases: Predicate

Logical AND over a tuple of operands.

Defined as a frozen dataclass like the other nodes, so it is hashable and comparable. The custom __init__ accepts the variadic form And(a, b, c).

Col dataclass

Col(name: str)

Bases: Term

The value of one column of the row, by name.

Compare dataclass

Compare(op: CmpOp, left: Term, right: Term)

Bases: Predicate

Two terms compared with one operator, such as >=; unknown when either term is None.

Greatest dataclass

Greatest()

Bases: _NullIgnoringExtremum

The largest non-null operand, or null when every operand is null. Variadic: Greatest(a, b, c).

Use it for "the maximum over several nullable columns", such as an allele frequency over ancestry groups, where one missing group must not hide the others. The SQL rendering is GREATEST(COALESCE(a, b, c), COALESCE(b, c, a), COALESCE(c, a, b)), which gives the same answer on BigQuery, whose GREATEST is NULL when any argument is NULL, and on DuckDB, whose GREATEST skips NULLs.

In dataclass

In(operand: Term, values: Iterable[Any])

Bases: Predicate

Whether a term equals one of a tuple of literal values: SQL term IN (v1, v2, ...).

Semantics follow SQL: a null term is unknown, a match is true, and otherwise the result is false. An empty tuple is false for every row, null term included, and renders to FALSE because IN () is not valid SQL. The values must be non-null literals of one type family (booleans, numbers, or strings); a None value is rejected because SQL makes x IN (..., NULL) unknown rather than true for a null x. Write "one of these values, or missing" as Or(In(term, values), IsNull(term)).

Values are stored as a tuple of built-in scalars (NumPy scalars are converted) with duplicates removed in first-occurrence order. A set is rejected because its iteration order, and so the SQL text, is not stable between processes.

IsNull dataclass

IsNull(operand: Term)

Bases: Predicate

Whether a term is null (a missing column or a None value counts as null in Python).

Unlike every other test it is always definite, True or False, never unknown. Write the negation as Not(IsNull(term)), which renders to NOT (term IS NULL).

Least dataclass

Least()

Bases: _NullIgnoringExtremum

The smallest non-null operand, or null when every operand is null. Variadic: Least(a, b, c).

Lit dataclass

Lit(value: Any)

Bases: Term

A constant value.

Not dataclass

Not(operand: Predicate)

Bases: Predicate

Logical NOT of one predicate; an unknown operand stays unknown.

Or dataclass

Or(*operands: Predicate)

Bases: Predicate

Logical OR over a tuple of operands.

A frozen dataclass like the other nodes. The custom __init__ accepts the variadic form Or(a, b, c).

Predicate

Bases: ABC

A boolean expression over columns, renderable to a Python callable and to SQL.

evaluate abstractmethod

evaluate(row: Mapping[str, Any]) -> bool | None

Evaluate against row with three-valued logic, returning True, False, or None (unknown).

to_sql abstractmethod

to_sql(
    col: SqlCol = _identity,
    *,
    dialect: SqlDialect = STANDARD,
) -> str

Render the predicate as a SQL boolean expression in dialect, naming each column through col.

to_python

to_python() -> Callable[[Mapping[str, Any]], bool]

Return a callable that tests a row and returns True only when the predicate is definitely true.

An unknown (None) result counts as not matching, the same as a SQL boolean filter.

SqlDialect

Bases: Enum

The SQL dialect a predicate renders to. It decides how a string literal is escaped.

STANDARD writes 'Alzheimer''s', as SQLite, DuckDB, and PostgreSQL read it. BIGQUERY writes 'Alzheimer\'s', as GoogleSQL reads it, and also escapes backslashes and control characters such as a newline. In GoogleSQL a doubled quote is a syntax error and a backslash starts an escape.

Term

Bases: ABC

A value-producing expression: a column, a literal, or a function of terms.

evaluate abstractmethod

evaluate(row: Mapping[str, Any]) -> Any

Return the term's value for row, or None if a referenced column is missing or None.

Eq

Eq(left: Term, right: Term) -> Compare

Return the predicate left == right.

Ge

Ge(left: Term, right: Term) -> Compare

Return the predicate left >= right.

Gt

Gt(left: Term, right: Term) -> Compare

Return the predicate left > right.

Le

Le(left: Term, right: Term) -> Compare

Return the predicate left <= right.

Lt

Lt(left: Term, right: Term) -> Compare

Return the predicate left < right.

Ne

Ne(left: Term, right: Term) -> Compare

Return the predicate left != right.