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.
import * as Scalar from "gizmodel/sql/types/scalar";Types
Cx
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.Dialectnow:i64bits:u64key:u64
Fn
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
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:i64max:i64volatile:boolvector:i64
Functions
some
function some(fn: Fn, min: i64, max: i64): Option<Scalar>A scalar function that is not volatile, with its argument counts.
Effects: fail.
volatile
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
function ok(v: Value): Value throws DbErrorV as the result of a scalar function.
nul
function nul(): Value throws DbErrorThe null value.
text
function text(s: string): Value throws DbErrorThe text value S.
int
function int(n: i64): Value throws DbErrorThe integer value N.
float
function float(f: f64): Value throws DbErrorThe float value F.
dateOut
function dateOut(cx: Cx, days: i64): Value throws DbErrorA date, timestamp or time a function returns: text in SQLite, whose dates are text.
Effects: fail, alloc.
tsOut
function tsOut(cx: Cx, us: i64): Value throws DbErrorThe timestamp US (microseconds) as the dialect returns it: text in SQLite.
Effects: fail, alloc.
timeOut
function timeOut(cx: Cx, us: i64): Value throws DbErrorThe time of day US (microseconds) as the dialect returns it: text in SQLite.
Effects: fail, alloc.
localNow
function localNow(cx: Cx): i64The statement clock as local time in the session's zone.
Effects: fail, alloc.
anyNull
function anyNull(args: Vec<Value>): boolWhether any of ARGS is null.
Effects: fail.
str
function str(v: Value, cx: Cx): stringThe text of a non-null value as string functions read it.
Effects: fail, alloc.
hasBlob
function hasBlob(args: Vec<Value>): boolWhether any of ARGS is a blob.
Effects: fail.
vectorOf
function vectorOf(v: Value): Option<Vec<f32>>The vector that V holds, or none.
Effects: fail, alloc.
charCount
function charCount(s: string): i64Characters (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
function charsIn(d: bytes, from: i64, to: i64): i64The 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
function joined(parts: Vec<string>, from: i64, to: i64): stringPARTS from FROM up to TO, joined.
Effects: fail, alloc.
charLen
function charLen(t: bytes, i: i64): i64The byte length of the UTF-8 character at I of T.
Effects: fail.
mix64
function mix64(x0: u64): u64SplitMix64's finalizer: a well-mixed 64-bit function of x, for random bits by position.
Effects: fail.
Constants
PRODUCT
const PRODUCT: i64 = 3Scalar.vector of inner_product: the product, where IP (pgvector's <#>) is its negation.