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

