# gizmodel/sql/batch

a batch of typed columns and the replies that carry batches (FinitePoll, Rows, Delivery). The record layer (gizmodel/query, gizmodel/source) reads them, and imports this leaf, not the executor (vm.giz), so it links no engine.

```gizlang
import * as Batch from "gizmodel/sql/batch";
```

## Types

### `Batch`

```gizlang
type Batch = { cols: Vec<Column>; types: Vec<Type>; n: i64; base: i64; ids: Vec<i64>; }
```

A batch: columns of equal length. Row i is at position `base + i` of its input, or `ids[i]`
once rows were selected (volatile functions draw their bits by position).

- `cols`: `Vec<M145.Column>`
- `types`: `Vec<M143.Type>`
- `n`: `i64`
- `base`: `i64`
- `ids`: `Vec<i64>`

### `FinitePoll`

```gizlang
type FinitePoll = | { kind: "batch"; batch: Batch; } | { kind: "blocked"; rows: i64; bytes: i64; } | { kind: "yield"; } | { kind: "done"; }
```

One poll of a finite batch reader: a batch, a refusal for more credit, a turn to yield, or the end.

- `batch`
- `blocked`
- `yield`
- `done`

### `Rows`

```gizlang
type Rows = { columns: Vec<string>; types: Vec<Type>; rows: Vec<Vec<Value>>; affected: i64; declared: Vec<string>; }
```

A statement's result: named, typed columns and rows (for a query or RETURNING), and how
many rows it changed. `declared` holds each column's Out.declared, or is empty.

- `columns`: `Vec<string>`
- `types`: `Vec<M143.Type>`
- `rows`: `Vec<Vec<M143.Value>>`
- `affected`: `i64`
- `declared`: `Vec<string>`

### `SignedBatch`

```gizlang
type SignedBatch = { batch: Batch; weight: i64; position: Position; }
```

Weight is uniform within a batch; positions name committed input, never event time.

- `batch`: `M152.Batch`
- `weight`: `i64`
- `position`: `gizlang_journal.Position`

### `Delivery`

```gizlang
type Delivery = { batches: Vec<SignedBatch>; through: Position; generation: string; }
```

A nonempty generation replaces the previous result with these batches, including an empty result.

- `batches`: `Vec<M152.SignedBatch>`
- `through`: `gizlang_journal.Position`
- `generation`: `string`

## Functions

### `cell`

```gizlang
function cell(b: Batch, c: i64, i: i64): Value
```

The value at row `i` of column `c` of batch `b`.

Effects: fail, alloc.

### `batchRows`

```gizlang
function batchRows(b: Batch, from: i64, to: i64): Vec<Vec<Value>>
```

The values of rows FROM..TO of B, a row each.

Effects: fail, alloc.

### `unnamed`

```gizlang
function unnamed(rows: Vec<Vec<Value>>): Rows
```

Rows with no column names, such as the answer of a function call, whose caller names the columns.

### `batchRange`

```gizlang
function batchRange(b: Batch, start: i64, end: i64): Batch
```

Rows [start, end) of `b`, at their positions; an empty (unread) column stays empty.

Effects: fail, alloc.

## Methods

### `Batch.posOf`

```gizlang
function Batch.posOf(self: Batch, i: i64): i64
```

The input position of row I of the batch.

Effects: fail.

