gizmodel/query
a typed read of stored records. A Query<R> says what to read and holds no connection; a Db (model/data.giz) runs it. from<R>() is every record of R; each operator takes a typed lambda and gives a new Query. The writes of a Shape's records (insert, update, delete) are built here too, as the tree every engine runs.
import * as Query from "gizmodel/query";Types
Assignment
type Assignment = { name: string; value: Value; adds: bool; }A field's new value in an UPDATE: VALUE, or its value plus VALUE when ADDS.
name:stringvalue:M143.Valueadds:bool
Functions
from
function from<R>(): Query<R>Every stored record of R, in key order.
of
function of(shape: Model.Shape): Query<Vec<Value>>Every row of SHAPE, as its values in field order, in key order.
Effects: fail, alloc.
condition
function condition<R>(find: Query<R>): Option<Tree.Expr>FIND's conditions as one, or none.
selection
function selection<R>(find: Query<R>, masks: Vec<Option<Tree.Expr>>): Tree.Select throws DbErrorThe SELECT of FIND: each field of its Model.Shape in field order (a field with a mask is NULL where the mask is not true; a computed field is its expression), FIND's conditions, its order (else the key order), skip and limit.
summing
function summing<R>(find: Query<R>, field: Lambda.Expr<R, i64>): Tree.Select throws DbErrorThe SELECT of the sum of the integer value that the lambda FIELD makes of each record FIND's conditions select: 0 when there are none. A DISTINCT find sums the distinct rows: the distinct read is the inner select, without its order or page.
counting
function counting<R>(find: Query<R>): Tree.Select throws DbErrorThe SELECT COUNT(*) of the records FIND's conditions select. A DISTINCT find counts the distinct rows.
prepared
function prepared<R>(find: Query<R>, masks: Vec<Option<Tree.Expr>>): Tree.Prepared<bool, R> throws DbErrorFIND as a typed query that any source runs (Tree.Prepared): no parameters, and the fields' slots, nullable where masked, as its outputs.
set
function set(name: string, value: Value): AssignmentThe field NAME set to VALUE.
increase
function increase(name: string, by: Value): AssignmentThe numeric field NAME increased by BY in the UPDATE itself (SET used = used + $1), so writers that race add both.
updating
function updating<R>(find: Query<R>, sets: Vec<Assignment>): Tree.Statement throws DbErrorThe UPDATE of the records FIND selects that sets SETS. It needs a condition: an update of every record is refused. A derived relation (a projection or a union) has no table of its own: refuse it clearly.
assigning
function assigning<R, A>(find: Query<R>, made: Lambda.Expr<R, A>): Tree.Statement throws DbErrorThe UPDATE of the records FIND selects that sets the fields of the record the lambda MADE makes, each to its value
over the stored record: (t) => ({ done: true, tries: t.tries + 1 }). A key or a computed field is not set. It needs
a condition and a table, as updating.
removing
function removing<R>(find: Query<R>): Tree.Statement throws DbErrorThe DELETE of the records FIND selects. It needs a condition: a delete of every record is refused. A derived relation has no table of its own, like an update.
Methods
Query.column
function Query.column<R>(self: Query<R>, name: string): Tree.Expression<Value>The column of the field NAME (or of the column NAME), typed by its field: for a condition of where or an order.
Query.where
function Query.where<R>(self: Query<R>, condition: Tree.Expression<bool>): Query<R>The records where CONDITION holds too.
Query.keyOf
function Query.keyOf<R>(self: Query<R>): stringThe key of the one record FIND names by an equality on the Model.Shape's only key field, as an insert tells it to the feed (wireValue); "" when FIND does not name one. A live view reads the record a write names, so a keyless notice of an update renders nothing: a streamed answer stopped at its first word (10/30).
Query.matching
function Query.matching<R>(self: Query<R>, names: Vec<string>, words: string, typeahead: bool = false): Query<R>The records whose @Search fields NAMES hold WORDS (GizDB's BM25 match; several fields score as one, each by its index's weight); order by Tree.score() for the best first. TYPEAHEAD finds what a search box shows as people type (Tree.matches).
Query.within
function Query.within<R, S>(self: Query<R>, name: string, other: Query<S>, column: string): Query<R>The records whose field NAME is one of the values of the field COLUMN of the records OTHER selects (IN a subquery).
Query.outside
function Query.outside<R, S>(self: Query<R>, name: string, other: Query<S>, column: string): Query<R>The records whose field NAME is none of the values of the field COLUMN of the records OTHER selects (NOT IN). A NULL among those values selects nothing, as in SQL: COLUMN is a field that is never NULL.
Query.either
function Query.either<R>(self: Query<R>, a: Query<R>, b: Query<R>): Query<R>The records that A or B selects, among those SELF selects: A and B are finds of the same records, and only their conditions count.
Query.values
function Query.values<R>(self: Query<R>): Query<Vec<Value>>The same read, each row as its values in field order.
Query.of
function Query.of<R>(self: Query<R>, shape: Model.Shape): Query<R>The same read of the records of SHAPE (the same type, kept elsewhere: a table of a records schema, Data.inSchema).
Query.distinct
function Query.distinct<R>(self: Query<R>): Query<R>The same read, with equal rows as one: in SQL, rows that agree on every selected value agree on NULL too.
Query.select
function Query.select<R, A>(self: Query<R>, made: Lambda.Expr<R, A>): Query<A>The rows of SELF made into records of the lambda's type: one relation of its cells, which every further operator composes on. The projection takes the record's order, page, size and DISTINCT through what it makes, whether its own.
Query.summarize
function Query.summarize<R, A>(self: Query<R>, made: Lambda.Expr<R, A>): Query<A>The rows of SELF summarized by the lambda MADE, as records of its type: MADE makes a record of aggregates (gizlang/expr
count(), sum, avg, min, max) and of other values, by which the rows are grouped:
(o): Total => ({ region: o.region, total: sum(o.price) }) makes one record for each region. The summary is one
relation, which every further operator composes on; SELF's order and page come after it.
Query.union
function Query.union<R>(self: Query<R>, other: Query<R>, all: bool = false): Query<R>The rows of SELF and OTHER together: equal rows as one (UNION), or every row as it is (UNION ALL, with all).
Neither side of the pair takes its own order, page or size; both select the same record, and the union they make
composes them after: the order of the two finds is the union's.
Query.orderBy
function Query.orderBy<R, T>(self: Query<R>, value: Tree.Expression<T>, descending: bool = false): Query<R>The records ordered by VALUE (an expression over their columns) after the earlier keys of the order.
Query.filter
function Query.filter<R>(self: Query<R>, test: Lambda.Expr<R, bool>): Query<R>The records where the lambda TEST holds (find<Order>().filter((o) => o.total > limit)): the lambda is lowered to SQL
by its fields' columns, and its captured values are the query's values.
Query.sorted
function Query.sorted<R, T>(self: Query<R>, key: Lambda.Expr<R, T>, descending: bool = false): Query<R>The records ordered by the lambda KEY after the earlier keys of the order (sorted((o) => o.total, true)).
Query.skip
function Query.skip<R>(self: Query<R>, n: i64): Query<R>The records after the first N.
Query.limit
function Query.limit<R>(self: Query<R>, n: i64): Query<R>At most N records.
Query.exists
function Query.exists<R>(self: Query<R>): Tree.Expression<bool> throws DbErrorWhether FIND selects a record (EXISTS), as a condition of another read or write: Tree.not of it holds when none is
there. A condition of FIND on a column of the outer table names it with that table (Tree.field(table, ...)).
Query.join
function Query.join<R, S, J>(self: Query<R>, other: Query<S>, on: Lambda.Expr<J, bool>): Query<J>The records J of each pair of a record of SELF and a record of OTHER for which ON holds (INNER JOIN). Each field of
J is the field of that name of one side: orders.join(people, (j: Line) => j.buyer === j.person && j.total > 0).
Query.leftJoin
function Query.leftJoin<R, S, J>(self: Query<R>, other: Query<S>, on: Lambda.Expr<J, bool>): Query<J>As join, and each record of SELF without a match once, the fields of OTHER none (LEFT JOIN): J declares them optional.
Query.rightJoin
function Query.rightJoin<R, S, J>(self: Query<R>, other: Query<S>, on: Lambda.Expr<J, bool>): Query<J>As join, and each record of OTHER without a match once, the fields of SELF none (RIGHT JOIN).
Query.fullJoin
function Query.fullJoin<R, S, J>(self: Query<R>, other: Query<S>, on: Lambda.Expr<J, bool>): Query<J>As join, and each record of either side without a match once (FULL OUTER JOIN): J declares every field optional.
Query.crossJoin
function Query.crossJoin<R, S, J>(self: Query<R>, other: Query<S>, pair: Lambda.Expr<J, bool>): Query<J>Every pair of a record of SELF and a record of OTHER (CROSS JOIN). PAIR names the type J and is not a condition: (j: Pair) => true.
Query.joinUsing
function Query.joinUsing<R, S, J>(self: Query<R>, other: Query<S>, names: Vec<string>, also: Lambda.Expr<J, bool>, kind: string = "inner"): Query<J>The join of KIND ("inner", "left", "right", "full") on the fields NAMES, which both sides have and J has once (USING).
Query.matched
function Query.matched<R, S, J>(self: Query<R>, other: Query<S>, on: Lambda.Expr<J, bool>): Query<R>The records of SELF that have a record of OTHER where ON holds (EXISTS): people.matched(orders, (j: Line) => j.person === j.buyer).
Query.unmatched
function Query.unmatched<R, S, J>(self: Query<R>, other: Query<S>, on: Lambda.Expr<J, bool>): Query<R>The records of SELF that have no record of OTHER where ON holds (NOT EXISTS).