GizStack
View .mdOpen in ChatGPTOpen in Claude

gizmodel/source

One typed data-source contract. An adapter reports its actual abilities and returns owned column pages. It never manufactures global snapshot/CDC semantics.

gizlang
import * as Source from "gizmodel/source";

Types

Capabilities

gizlang
type Capabilities = { schema: bool; projection: bool; filter: bool; group: bool; join: bool; snapshot: bool; changeLog: bool; write: bool; transaction: bool; cancel: bool; compute: bool; order: bool; limit: bool; window: bool; set: bool; }

What a source can do itself: the parts of a query that it runs, and whether it gives snapshots, a change log, writes and transactions.

  • schema: bool
  • projection: bool
  • filter: bool
  • group: bool
  • join: bool
  • snapshot: bool
  • changeLog: bool
  • write: bool
  • transaction: bool
  • cancel: bool
  • compute: bool
  • order: bool
  • limit: bool
  • window: bool
  • set: bool

Semantics

gizlang
type Semantics = { dialect: string; collation: string; timezone: string; nulls: string; }

How a source compares and shows values: its SQL dialect, collation, time zone and null order.

  • dialect: string
  • collation: string
  • timezone: string
  • nulls: string

Version

gizlang
type Version = { source: string; revision: string; snapshot: bool; }

Revisions remain per source; "snapshot=false" is never upgraded by a federation.

  • source: string
  • revision: string
  • snapshot: bool

Request

gizlang
type Request = { tree: Select; parameters: Vec<Typed.Slot>; values: Vec<Value>; outputs: Vec<Typed.Slot>; rows: i64; bytes: i64; sql: string; }

A query for a source: its tree, parameters and their values, outputs, and the most rows and bytes to read.

  • tree: M151.Select
  • parameters: Vec<M142.Slot>
  • values: Vec<M143.Value>
  • outputs: Vec<M142.Slot>
  • rows: i64
  • bytes: i64
  • sql: string

Cursor

gizlang
type Cursor = { slots: Vec<Typed.Slot>; versions: Vec<Version>; poll: (rows: i64, bytes: i64) => FinitePoll throws DbError; dispose: () => bool throws DbError; }

The open result of a query: its columns, the versions of the sources that it reads, and how to poll and close it.

  • slots: Vec<M142.Slot>
  • versions: Vec<M140.Version>
  • poll: (rows: i64, bytes: i64) => M152.FinitePoll throws M129.DbError
  • dispose: () => bool throws M129.DbError

Source

gizlang
type Source = { identity: string; semantics: Semantics; capabilities: Capabilities; prepare: (request: Request) => Cursor throws DbError; change: (commands: Vec<Statement>) => i64 throws DbError; read: Option<NativeRead>; version: () => string throws DbError; }

A data source that a query reads: its identity, semantics and capabilities, and how to prepare queries and run changes.

  • identity: string
  • semantics: M140.Semantics
  • capabilities: M140.Capabilities
  • prepare: (request: M140.Request) => M140.Cursor throws M129.DbError
  • change: (commands: Vec<M151.Statement>) => i64 throws M129.DbError
  • read: _gizlang_sdk_core.Option<(sql: string, rows: i64, bytes: i64) => M140.Cursor throws M129.DbError>
  • version: () => string throws M129.DbError — The version of the data the source reads now, "" when it has none: two reads in one version see the same data (model/policy.giz Kept).

Requirement

gizlang
type Requirement = { snapshot: bool; changeLog: bool; write: bool; transaction: bool; }

What a caller needs of a source.

  • snapshot: bool
  • changeLog: bool
  • write: bool
  • transaction: bool

Descriptor

gizlang
type Descriptor = { version: string; identity: string; revision: bytes; semantics: Semantics; capabilities: Capabilities; maxRows: i64; maxBytes: i64; }

This is the adapter contract revision, not a fabricated data revision. Actual data cuts remain Cursor.versions and are scoped to each source.

  • version: string
  • identity: string
  • revision: bytes
  • semantics: M140.Semantics
  • capabilities: M140.Capabilities
  • maxRows: i64
  • maxBytes: i64

TextRows

gizlang
type TextRows = { columns: Vec<string>; rows: Vec<Vec<Option<string>>>; }

A text client's answer: the column names the database gives and the text cells (none for NULL).

  • columns: Vec<string>
  • rows: Vec<Vec<_gizlang_sdk_core.Option<string>>>

TextClient

gizlang
type TextClient = { query: (sql: string, parameters: Vec<Option<string>>, kept: bool) => TextRows throws DbError; atomic: (statements: Vec<string>) => i64 throws DbError; numbered: bool; version: () => string throws DbError; reader?: (sql: string, parameters: Vec<Option<string>>) => Sql.Reader throws DbError; }

A database client that runs SQL text with text parameters and gives text cells (gizlang/sql/sqlite, gizlang/sql/postgres). atomic runs statements in one transaction. A query that is KEPT has an answer that depends only on the data it reads (ast.giz keepable): the client may keep it until the data changes. With reader the client steps a row at a time (SQLite): a page then reads rows as they come, and nothing holds a whole answer.

  • query: (sql: string, parameters: Vec<_gizlang_sdk_core.Option<string>>, kept: bool) => M140.TextRows throws M129.DbError
  • atomic: (statements: Vec<string>) => i64 throws M129.DbError
  • numbered: bool
  • version: () => string throws M129.DbError — The version of the data (Source.version).
  • reader: _gizlang_sdk_core.Option<(sql: string, parameters: Vec<_gizlang_sdk_core.Option<string>>) => gizlang_sql.Reader throws M129.DbError>

Functions

pinSchema

gizlang
function pinSchema(expected: bytes, slots: Vec<Typed.Slot>): bool throws DbError

Database-first callers pin observed result schemas rather than guessing a row type.

Effects: fail, alloc.

federated

gizlang
function federated(sources: Vec<Source>, atomic: bool, live: bool): Vec<Version> throws DbError

A federation requires identical semantics for a moved calculation and keeps source frontiers distinct. Atomic distributed writes are never implied.

Effects: fail, alloc.

document

gizlang
function document(identity: string, slots: Vec<Typed.Slot>, text: string): Source throws DbError

Arrays of records are the shared JSON/API/SaaS/spreadsheet export boundary. Nested fields are explicit text/extension codecs; no DOM f64 round-trip occurs.

Effects: fail, alloc.

semantics

gizlang
function semantics(dialect: string): Semantics throws DbError

The semantics of a SQL engine that an external source runs: its dialect, the collation of its text, its time zone and how it types NULL. A federation requires equal semantics.

Effects: fail, alloc.

text

gizlang
function text(client: TextClient, identity: string, semantics: Semantics): Source

A source on a text client. A query's declared output slots type the text cells; a query that declares none (discover) gets the columns the database names, each cell kept as nullable text. It has no snapshot or change log, so a watch is refused as a missing capability.

Effects: fail, alloc.

mutations

gizlang
function mutations(commands: Vec<Statement>, dialect: string): Vec<string> throws DbError

The SQL of an external source's batch of COMMANDS in DIALECT, each with its literals written in: at most 1024.

Effects: fail, alloc.

projection

gizlang
function projection(request: Request, identity: string): bool

Whether REQUEST only projects table IDENTITY: no filter, grouping, order, bound, join or parameter, which a source that pushes nothing down would answer wrong.

Effects: fail.

sqlFault

gizlang
function sqlFault(e: Sql.SqlError): DbError

A database's failure as a DbError: its SQLSTATE (HY000 when it has none) and its native code.

Effects: fail, alloc.

database

gizlang
function database(store: Sql.Database, identity: string): Source

A source on a database of gizlang/sql (SQLite, PostgreSQL or a GizDB server, MySQL, an ODBC data source): its SQL text runs as written, and the declared output slots type the text cells. The one adapter of every SQL database. A database the SQLite driver serves steps its rows, so a page reads them as they come; the others answer a whole read here, and their reader is refused as a missing cursor.

Effects: fail, alloc.

Methods

Source.describe

gizlang
function Source.describe(self: Source): Descriptor

The descriptor of the source: its contract version, identity, semantics, capabilities and limits.

Effects: fail, alloc.

Source.admit

gizlang
function Source.admit(self: Source, request: Request, need: Requirement, revision: bytes): bool throws DbError

Admit an exact typed request under a pinned adapter contract. The provider's prepare/binder remains the final authority for its actual operator support.

Effects: fail, alloc.

Source.request

gizlang
function Source.request(self: Source, request: Request, need: Requirement): bool throws DbError

Source.admit of a request to this source itself, whose contract is the one in hand: no revision to compare. Each A typed read hashed the descriptor twice to compare it with itself (a sixth of a one-row read, 2026-10-31).

Effects: fail, alloc.

Source.require

gizlang
function Source.require(self: Source, need: Requirement): bool throws DbError

Fails with an error that names the first capability of NEED that the source does not have.

Effects: fail, alloc.

Source.transaction

gizlang
function Source.transaction<T>(self: Source, commands: Vec<Statement>, result: T): T throws DbError

Runs COMMANDS as one transaction of the source; RESULT when they all succeed.

Source.discover

gizlang
function Source.discover(self: Source, tree: Select, parameters: Vec<Typed.Slot>, values: Vec<Value>, rows: i64, bytes: i64): Cursor throws DbError

A cursor of TREE with PARAMETERS and VALUES, after the source admits each part of it, reading at most ROWS rows and BYTES bytes.

Effects: fail, read, write, console, io, alloc.