docs menu

Module Source.Pred

Predicates on one row: the filters that sources apply.

A predicate compares columns of the source against values. It means what its filter means in talon: a comparison uses talon's total order (Type.compare_value) and is null when the column's value is null, and Pred.t.Not, Pred.t.And and Pred.t.Or are Kleene's, so a row passes a predicate iff the predicate is true on it. A source answers Exact only for a predicate whose meaning it honours entirely: for example, a float column's minimum and maximum prune a row group only when the source knows the group holds no NaN, since NaN passes >, >= and <>.

#type value =

#| Value : 'a Type.t * 'a -> value
(*
The type for values. Value (ty, v) is v at the type ty that the comparison is made in, which holds v (Type.holds). It is the column's type, or a type that contains it (Type.common), such as string for a categorical column, which then compares by text rather than by dictionary position. For an extension column it is the storage type, and v is the value's storage. v is a value of ty exactly, as ty stores it: a float32 value is rounded to float32.
*)

#type t =

#| Cmp of string * [ `Eq | `Ne | `Lt | `Le | `Gt | `Ge ] * value
(*
Cmp (c, op, v) compares the column c to v with op: `Eq is =, `Ne is <>, `Lt is <, `Le is <=, `Gt is > and `Ge is >=. It is null where c is null.
*)
#| In of string * value list
(*
In (c, vs) is true iff the column c is the same key as one of vs, which have one type, and false elsewhere, null c included. In (c, []) is false.
*)
#| Null of string
(*
Null c is true iff the column c is null.
*)
#| Valid of string
(*
Valid c is true iff the column c is not null.
*)
#| And of t list
(*
And ps is false if one of ps is, else null if one is null, else true. And [] is true.
*)
#| Or of t list
(*
Or ps is true if one of ps is, else null if one is null, else false. Or [] is false.
*)
#| Not of t
(*
Not p is the negation of p, null where p is.
*)

The type for predicates.

#val filter : Schema.t -> t -> (bool, Expr.row) Expr.t option

filter s p is the filter that p is over a table of the columns s describes: it is true, false or null where p is, so Query.filter of it keeps the rows that pass p. A source that answers Exact can apply a conjunct with it, on each batch it reads. It is None if p names a column that s lacks, or one whose type is or contains an extension type, which a filter reads only with its declaration (Ext.col).