gizmodel/semantic
Analytical meaning is metadata attached to stable declarations. Calculations remain the existing typed SQL AST/Rel; this module owns grain/unit validation and the pivot of a certified metric (its cells and exact totals).
import * as Semantic from "gizmodel/semantic";Types
Dataset
type Dataset = { declaration: string; table: string; grain: Vec<string>; fields: Vec<Typed.Contract>; }A dataset of the model: its declaration, table, grain (the columns that make a row unique) and fields.
declaration:stringtable:stringgrain:Vec<string>fields:Vec<M142.Contract>
Relationship
type Relationship = { declaration: string; many: string; one: string; foreign: Vec<string>; primary: Vec<string>; }A many-to-one relationship between two datasets, by their columns.
declaration:stringmany:stringone:stringforeign:Vec<string>primary:Vec<string>
Meaning
type Meaning = { declaration: string; unit: string; currency: string; calendar: string; additive: Vec<string>; }What the values of a field mean: their unit, currency and calendar, and the axes across which they add up.
declaration:stringunit:stringcurrency:stringcalendar:stringadditive:Vec<string>
Metric
type Metric = { declaration: string; dataset: string; meaning: Meaning; dependencies: Vec<string>; certified: bool; query: Select; measure: string; }A metric: its dataset, meaning, dependencies, query and measure, and whether it is certified.
declaration:stringdataset:stringmeaning:M139.Meaningdependencies:Vec<string>certified:boolquery:M151.Selectmeasure:string
Display
type Display = { declaration: string; label: string; format: string; widget: string; }How a field is shown: its label, format and widget.
declaration:stringlabel:stringformat:stringwidget:string
Dimension
type Dimension = { name: string; power: i64; }A physical dimension and its power in a unit ("length", 2).
name:stringpower:i64
Unit
type Unit = { declaration: string; dimensions: Vec<Dimension>; }Units name normalized products of physical dimensions. Conversion is an explicit calculation; matching dimensions never silently rescales a value.
declaration:stringdimensions:Vec<M139.Dimension>
Model
type Model = { datasets: Vec<Dataset>; relationships: Vec<Relationship>; metrics: Vec<Metric>; schemas: Vec<Schema>; units: Vec<Unit>; fields: Vec<Meaning>; }A semantic model: datasets, relationships, metrics, schemas, units and field meanings.
datasets:Vec<M139.Dataset>relationships:Vec<M139.Relationship>metrics:Vec<M139.Metric>schemas:Vec<M143.Schema>units:Vec<M139.Unit>fields:Vec<M139.Meaning>
Axes
type Axes = { dimensions: Vec<string>; grouping: Vec<string>; time: string; timezone: string; }The approved axes of an interactive aggregate over an external relation. GROUPING is its default display grain, not a proof of a physical primary key (Dataset.grain). Source time zones describe values and never convert them.
dimensions:Vec<string>grouping:Vec<string>time:stringtimezone:string
Pivot
type Pivot = { rows: string; columns: string; rowTotals: bool; columnTotals: bool; cells: i64; }A pivot of a certified metric. The registered query of the metric groups by
exactly two outputs; rows and columns name them. A row total rolls the
measure up across columns, a column total across rows. Each total needs the
additivity of the metric across that axis (Meaning.additive): all axes is
additive, some axes is semiadditive, no axis is nonadditive. cells is the
limit of row and column pairs, 1 to PIVOT_CELLS.
rows:stringcolumns:stringrowTotals:boolcolumnTotals:boolcells:i64
Crosstab
type Crosstab = { pivot: Pivot; measure: string; rowKeys: Vec<Value>; columnKeys: Vec<Value>; cells: Vec<Option<Value>>; rowTotals: Vec<Value>; columnTotals: Vec<Value>; total: Option<Value>; }The computed pivot. cells is row-major. None marks a pair without a result
row; a NULL measure is a value. Keys keep their exact values, so a NULL key
differs from the text "NULL". NULL keys sort last.
pivot:M139.Pivotmeasure:stringrowKeys:Vec<M143.Value>columnKeys:Vec<M143.Value>cells:Vec<_gizlang_sdk_core.Option<M143.Value>>rowTotals:Vec<M143.Value>columnTotals:Vec<M143.Value>total:_gizlang_sdk_core.Option<M143.Value>
Observed
type Observed = { table: string; schema: string; }A table that a certificate observed, and its schema.
table:stringschema:string
Certificate
type Certificate = { metric: string; revision: i64; record: string; meaning: string; formula: string; parameters: string; outputs: string; publisher: string; schemas: Vec<Observed>; }A certificate that a query computes a metric: what was certified, by whom, and the schemas it observed.
metric:stringrevision:i64record:stringmeaning:stringformula:stringparameters:stringoutputs:stringpublisher:stringschemas:Vec<M139.Observed>
Functions
validateAxes
function validateAxes(axes: Axes, columns: Vec<string>, grouping: Vec<string>): bool throws DbErrorValidates interactive axes against the columns authorized for this reader. It grants no native certification.
Effects: fail, alloc.
dimensions
function dimensions(input: Vec<Dimension>): Vec<Dimension> throws DbErrorA bounded canonical exponent vector is the sole unit algebra.
Effects: fail, alloc.
product
function product(left: Vec<Dimension>, right: Vec<Dimension>, divide: bool): Vec<Dimension> throws DbErrorThe dimensions of the product (or, when DIVIDE, the quotient) of two units. It fails when a list is not valid.
Effects: fail, alloc.
validateModel
function validateModel(model: Model): bool throws DbErrorChecks that MODEL is within its limits and that each name it uses is declared.
Effects: fail, alloc.
validateQuery
function validateQuery(model: Model, metric: Metric, tree: Select, rollup: Vec<string>): bool throws DbErrorSUM across a one-to-many join cannot silently multiply the fact grain.
Effects: fail, alloc.
certified
function certified<P, R>(model: Model, metric: Metric, query: Tree.Prepared<P, R>, rollup: Vec<string>): Tree.Prepared<P, R> throws DbErrorQUERY when METRIC is certified and QUERY computes it by its definition, rolled up by ROLLUP; else an error that says why.
pivot
function pivot(model: Model, metric: Metric, spec: Pivot, outputs: Vec<Typed.Slot>, rows: Vec<Vec<Value>>): Crosstab throws DbErrorThe server arranges the result of the certified query (outputs, rows) and
adds the totals exactly. It refuses a total that the metric does not declare
additive, and a grid of more than spec.cells cells.
Effects: fail, alloc.
executionDigest
function executionDigest(model: Model, metric: Metric, parameters: Vec<Typed.Slot>, outputs: Vec<Typed.Slot>): bytes throws DbErrorA declaration's certification request is distinct from native publication. Access verifies the current authorized catalog receipt on every delivery.
Effects: fail, alloc.
certificate
function certificate(model: Model, metric: Metric, parameters: Vec<Typed.Slot>, outputs: Vec<Typed.Slot>, revision: i64, publisher: string): Certificate throws DbErrorThe certificate of METRIC of MODEL with its PARAMETERS and OUTPUTS, at REVISION, by PUBLISHER.
Effects: fail, alloc.
certificateRecord
function certificateRecord(receipt: Certificate): string throws DbErrorThe certificate as its encoded record.
Effects: fail, alloc.
readCertificate
function readCertificate(payload: string): Certificate throws DbErrorThe certificate of an encoded record. It fails when the record is not valid.
Effects: fail, alloc.
meaningDigest
function meaningDigest(metric: Metric): bytes throws DbErrorMeaning, policy and display hashes deliberately have independent dependency sets.
Effects: fail, alloc.
definitionDigest
function definitionDigest(model: Model, metric: Metric): bytes throws DbErrorChecked meaning includes its typed lineage, units and dependent metrics. Presentation and physical indexes deliberately do not enter this identity.
Effects: fail, alloc.
displayDigest
function displayDigest(display: Vec<Display>): bytesThe digest of the display settings, which a certificate keeps.
Effects: fail, alloc.
metricRecord
function metricRecord(model: Model, metric: Metric): string throws DbErrorA catalog payload is derived from checked meaning; callers cannot replace it with unrelated text while keeping a certified declaration identity.
Effects: fail, alloc.
Constants
PIVOT_CELLS
const PIVOT_CELLS: i64 = 4096The most cells (row and column pairs) of a pivot.