GizStack
View .mdOpen in ChatGPTOpen in Claude

gizmodel/sql/types/scalar

What every SQL function shares: the context it may read (Cx), the function value (Fn, Scalar) and the helpers that make and read argument values. func.giz and the fn*.giz modules use it.

gizlang
import * as Scalar from "gizmodel/sql/types/scalar";

Types

Cx

gizlang
type Cx = { dialect: Dialect; now: i64; bits: u64; key: u64; }

What a function may read besides its arguments: the dialect, the statement's time (microseconds since the epoch, one value for the whole statement as SQL requires) and, for a volatile function, 64 random bits the caller draws for this call (distinct per row) and the session's secret key, 64 bits it never shows, which make a value from the bits unguessable (uuid). Functions are pure otherwise, so plans call them from every core.

  • dialect: M158.Dialect
  • now: i64
  • bits: u64
  • key: u64

Fn

gizlang
type Fn = (args: Vec<Value>, cx: Cx) => Value throws DbError effects {fail, alloc}

The implementation of a scalar function: its arguments and context to its value.

Scalar

gizlang
type Scalar = { fn: Fn; min: i64; max: i64; volatile: bool; vector: i64; }

A scalar function: its implementation, the argument counts it takes (max -1: any), whether each call needs fresh random bits (random(), uuid()), and for a distance of two vectors the metric a batch computes it by (db/core/vector.giz L2, COSINE, IP, or PRODUCT for the inner product itself; -1 for other functions).

  • fn: (args: Vec<M143.Value>, cx: M163.Cx) => M143.Value throws M129.DbError effects { fail, alloc }
  • min: i64
  • max: i64
  • volatile: bool
  • vector: i64

Functions

some

gizlang
function some(fn: Fn, min: i64, max: i64): Option<Scalar>

A scalar function that is not volatile, with its argument counts.

Effects: fail.

volatile

gizlang
function volatile(fn: Fn, min: i64, max: i64): Option<Scalar>

A volatile scalar function (it needs fresh random bits), with its argument counts.

Effects: fail.

ok

gizlang
function ok(v: Value): Value throws DbError

V as the result of a scalar function.

nul

gizlang
function nul(): Value throws DbError

The null value.

text

gizlang
function text(s: string): Value throws DbError

The text value S.

int

gizlang
function int(n: i64): Value throws DbError

The integer value N.

float

gizlang
function float(f: f64): Value throws DbError

The float value F.

dateOut

gizlang
function dateOut(cx: Cx, days: i64): Value throws DbError

A date, timestamp or time a function returns: text in SQLite, whose dates are text.

Effects: fail, alloc.

tsOut

gizlang
function tsOut(cx: Cx, us: i64): Value throws DbError

The timestamp US (microseconds) as the dialect returns it: text in SQLite.

Effects: fail, alloc.

timeOut

gizlang
function timeOut(cx: Cx, us: i64): Value throws DbError

The time of day US (microseconds) as the dialect returns it: text in SQLite.

Effects: fail, alloc.

localNow

gizlang
function localNow(cx: Cx): i64

The statement clock as local time in the session's zone.

Effects: fail, alloc.

anyNull

gizlang
function anyNull(args: Vec<Value>): bool

Whether any of ARGS is null.

Effects: fail.

str

gizlang
function str(v: Value, cx: Cx): string

The text of a non-null value as string functions read it.

Effects: fail, alloc.

hasBlob

gizlang
function hasBlob(args: Vec<Value>): bool

Whether any of ARGS is a blob.

Effects: fail.

vectorOf

gizlang
function vectorOf(v: Value): Option<Vec<f32>>

The vector that V holds, or none.

Effects: fail, alloc.

charCount

gizlang
function charCount(s: string): i64

Characters (code points) of a text, as SQL's length and substr count them. Its bytes go to charsIn borrowed: bound to a name they took a reference, two atomic writes to the string's header when threads share it (ClickBench Q27's length(URL)).

Effects: fail.

charsIn

gizlang
function charsIn(d: bytes, from: i64, to: i64): i64

The characters of UTF-8 D[FROM, TO): its bytes less its continuation bytes (10xxxxxx), eight at a time. A byte at a time, ClickBench Q27's length(URL) was 79% of the query.

Effects: fail.

joined

gizlang
function joined(parts: Vec<string>, from: i64, to: i64): string

PARTS from FROM up to TO, joined.

Effects: fail, alloc.

charLen

gizlang
function charLen(t: bytes, i: i64): i64

The byte length of the UTF-8 character at I of T.

Effects: fail.

mix64

gizlang
function mix64(x0: u64): u64

SplitMix64's finalizer: a well-mixed 64-bit function of x, for random bits by position.

Effects: fail.

Constants

PRODUCT

gizlang
const PRODUCT: i64 = 3

Scalar.vector of inner_product: the product, where IP (pgvector's <#>) is its negation.