GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

gizlang
import * as Query from "gizmodel/query";

Types

Assignment

gizlang
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: string
  • value: M143.Value
  • adds: bool

Functions

from

gizlang
function from<R>(): Query<R>

Every stored record of R, in key order.

of

gizlang
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

gizlang
function condition<R>(find: Query<R>): Option<Tree.Expr>

FIND's conditions as one, or none.

selection

gizlang
function selection<R>(find: Query<R>, masks: Vec<Option<Tree.Expr>>): Tree.Select throws DbError

The 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

gizlang
function summing<R>(find: Query<R>, field: Lambda.Expr<R, i64>): Tree.Select throws DbError

The 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

gizlang
function counting<R>(find: Query<R>): Tree.Select throws DbError

The SELECT COUNT(*) of the records FIND's conditions select. A DISTINCT find counts the distinct rows.

prepared

gizlang
function prepared<R>(find: Query<R>, masks: Vec<Option<Tree.Expr>>): Tree.Prepared<bool, R> throws DbError

FIND as a typed query that any source runs (Tree.Prepared): no parameters, and the fields' slots, nullable where masked, as its outputs.

set

gizlang
function set(name: string, value: Value): Assignment

The field NAME set to VALUE.

increase

gizlang
function increase(name: string, by: Value): Assignment

The numeric field NAME increased by BY in the UPDATE itself (SET used = used + $1), so writers that race add both.

updating

gizlang
function updating<R>(find: Query<R>, sets: Vec<Assignment>): Tree.Statement throws DbError

The 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

gizlang
function assigning<R, A>(find: Query<R>, made: Lambda.Expr<R, A>): Tree.Statement throws DbError

The 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

gizlang
function removing<R>(find: Query<R>): Tree.Statement throws DbError

The 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

gizlang
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

gizlang
function Query.where<R>(self: Query<R>, condition: Tree.Expression<bool>): Query<R>

The records where CONDITION holds too.

Query.keyOf

gizlang
function Query.keyOf<R>(self: Query<R>): string

The 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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
function Query.values<R>(self: Query<R>): Query<Vec<Value>>

The same read, each row as its values in field order.

Query.of

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
function Query.skip<R>(self: Query<R>, n: i64): Query<R>

The records after the first N.

Query.limit

gizlang
function Query.limit<R>(self: Query<R>, n: i64): Query<R>

At most N records.

Query.exists

gizlang
function Query.exists<R>(self: Query<R>): Tree.Expression<bool> throws DbError

Whether 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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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

gizlang
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).