docs menu

Module Talon.Ext

Extension declarations.

An extension type is a named type stored as another (Type.ext). A declaration gives it OCaml values 'e, converted to and from its storage values 's. It is the only way to read an extension column's values or compute on them: no Col handle binds one. A library's claim to an extension's name is a convention, as in Arrow; what it controls is 'e, whose values come only from dec and enc.

Without a declaration, an extension column moves through the order-free structural operations: keep, Expr.each, filtering, gathering, appending, joining and grouping by key identity on its storage. Its order, and computation on its values, need a declaration.

#type ('e, 's) t

The type for declarations of extensions whose values read as 'e and are stored as 's.

val v : 
  name:string ->
  ?metadata:string ->
  ordered:bool ->
  's Type.t ->
  dec:('s -> 'e) ->
  enc:('e -> 's) ->
  ('e, 's) t

v ~name ~metadata ~ordered storage ~dec ~enc declares the extension type Type.ext ~name ~metadata storage with:

dec, which reads a stored value as 'e: Query.values and Column.values decode with it;
enc, which stores an 'e: literals, Expr.const values, Expr.is_in values and Expr.cut edges encode with it. It must be injective;
ordered, a promise that the order of stored values is the order of the values, as for an epoch stored normalized. With ~ordered:false, Expr.min, Expr.max, Expr.arg_min, Expr.arg_max, Expr.rank, Expr.cut and < are problems on its values. Sort and join keys are names, which no declaration binds.

metadata defaults to "".

Raises Invalid_argument as Type.ext does.

#val col : ('e, 's) t -> string -> ('e, Expr.row) Expr.t

col e name is the column name read through e. It binds only a column whose type is e's: the same name, metadata and storage type, so a declaration of metres never binds a column of kilograms.