# gizdb: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). ```gizlang import * as Semantic from "gizdb:semantic"; ``` ## Types ### `Dataset` ```gizlang type Dataset = { declaration: string; table: string; grain: Vec; fields: Vec; } ``` A dataset of the model: its declaration, table, grain (the columns that make a row unique) and fields. - `declaration`: `string` - `table`: `string` - `grain`: `Vec` - `fields`: `Vec` ### `Relationship` ```gizlang type Relationship = { declaration: string; many: string; one: string; foreign: Vec; primary: Vec; } ``` A many-to-one relationship between two datasets, by their columns. - `declaration`: `string` - `many`: `string` - `one`: `string` - `foreign`: `Vec` - `primary`: `Vec` ### `Meaning` ```gizlang type Meaning = { declaration: string; unit: string; currency: string; calendar: string; additive: Vec; } ``` What the values of a field mean: their unit, currency and calendar, and the axes across which they add up. - `declaration`: `string` - `unit`: `string` - `currency`: `string` - `calendar`: `string` - `additive`: `Vec` ### `Metric` ```gizlang type Metric = { declaration: string; dataset: string; meaning: Meaning; dependencies: Vec; certified: bool; query: Select; measure: string; } ``` A metric: its dataset, meaning, dependencies, query and measure, and whether it is certified. - `declaration`: `string` - `dataset`: `string` - `meaning`: `M53.Meaning` - `dependencies`: `Vec` - `certified`: `bool` - `query`: `_gizlang_lib_db__sql__ast.Select` - `measure`: `string` ### `Display` ```gizlang type Display = { declaration: string; label: string; format: string; widget: string; } ``` How a field is shown: its label, format and widget. - `declaration`: `string` - `label`: `string` - `format`: `string` - `widget`: `string` ### `Dimension` ```gizlang type Dimension = { name: string; power: i64; } ``` A physical dimension and its power in a unit ("length", 2). - `name`: `string` - `power`: `i64` ### `Unit` ```gizlang type Unit = { declaration: string; dimensions: Vec; } ``` Units name normalized products of physical dimensions. Conversion is an explicit calculation; matching dimensions never silently rescales a value. - `declaration`: `string` - `dimensions`: `Vec` ### `Model` ```gizlang type Model = { datasets: Vec; relationships: Vec; metrics: Vec; schemas: Vec; units: Vec; fields: Vec; } ``` A semantic model: datasets, relationships, metrics, schemas, units and field meanings. - `datasets`: `Vec` - `relationships`: `Vec` - `metrics`: `Vec` - `schemas`: `Vec` - `units`: `Vec` - `fields`: `Vec` ### `Pivot` ```gizlang 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`: `string` - `columns`: `string` - `rowTotals`: `bool` - `columnTotals`: `bool` - `cells`: `i64` ### `Crosstab` ```gizlang type Crosstab = { pivot: Pivot; measure: string; rowKeys: Vec; columnKeys: Vec; cells: Vec>; rowTotals: Vec; columnTotals: Vec; total: Option; } ``` 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`: `M53.Pivot` - `measure`: `string` - `rowKeys`: `Vec` - `columnKeys`: `Vec` - `cells`: `Vec<_gizlang_sdk_core.Option>` - `rowTotals`: `Vec` - `columnTotals`: `Vec` - `total`: `_gizlang_sdk_core.Option` ### `Observed` ```gizlang type Observed = { table: string; schema: string; } ``` A table that a certificate observed, and its schema. - `table`: `string` - `schema`: `string` ### `Certificate` ```gizlang type Certificate = { metric: string; revision: i64; record: string; meaning: string; formula: string; parameters: string; outputs: string; publisher: string; schemas: Vec; } ``` A certificate that a query computes a metric: what was certified, by whom, and the schemas it observed. - `metric`: `string` - `revision`: `i64` - `record`: `string` - `meaning`: `string` - `formula`: `string` - `parameters`: `string` - `outputs`: `string` - `publisher`: `string` - `schemas`: `Vec` ## Functions ### `dimensions` ```gizlang function dimensions(input: Vec): Result, DbError> ``` A bounded canonical exponent vector is the sole unit algebra. Effects: fail. ### `product` ```gizlang function product(left: Vec, right: Vec, divide: bool): Result, DbError> ``` The dimensions of the product (or, when DIVIDE, the quotient) of two units. It fails when a list is not valid. Effects: fail. ### `validateModel` ```gizlang function validateModel(model: Model): Result ``` Checks that MODEL is within its limits and that each name it uses is declared. Effects: fail. ### `validateQuery` ```gizlang function validateQuery(model: Model, metric: Metric, tree: Select, rollup: Vec): Result ``` SUM across a one-to-many join cannot silently multiply the fact grain. Effects: fail. ### `certified` ```gizlang function certified(model: Model, metric: Metric, query: Query.Prepared, rollup: Vec): Result, DbError> ``` QUERY when METRIC is certified and QUERY computes it by its definition, rolled up by ROLLUP; else an error that says why. ### `pivot` ```gizlang function pivot(model: Model, metric: Metric, spec: Pivot, outputs: Vec, rows: Vec>): Result ``` The 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. ### `executionDigest` ```gizlang function executionDigest(model: Model, metric: Metric, parameters: Vec, outputs: Vec): Result ``` A declaration's certification request is distinct from native publication. Access verifies the current authorized catalog receipt on every delivery. Effects: fail. ### `certificate` ```gizlang function certificate(model: Model, metric: Metric, parameters: Vec, outputs: Vec, revision: i64, publisher: string): Result ``` The certificate of METRIC of MODEL with its PARAMETERS and OUTPUTS, at REVISION, by PUBLISHER. Effects: fail. ### `certificateRecord` ```gizlang function certificateRecord(receipt: Certificate): Result ``` The certificate as its encoded record. Effects: fail. ### `readCertificate` ```gizlang function readCertificate(payload: string): Result ``` The certificate of an encoded record. It fails when the record is not valid. Effects: fail. ### `meaningDigest` ```gizlang function meaningDigest(metric: Metric): Result ``` Meaning, policy and display hashes deliberately have independent dependency sets. Effects: fail. ### `definitionDigest` ```gizlang function definitionDigest(model: Model, metric: Metric): Result ``` Checked meaning includes its typed lineage, units and dependent metrics. Presentation and physical indexes deliberately do not enter this identity. Effects: fail. ### `displayDigest` ```gizlang function displayDigest(display: Vec): bytes ``` The digest of the display settings, which a certificate keeps. Effects: fail. ### `metricRecord` ```gizlang function metricRecord(model: Model, metric: Metric): Result ``` A catalog payload is derived from checked meaning; callers cannot replace it with unrelated text while keeping a certified declaration identity. Effects: fail. ## Constants ### `PIVOT_CELLS` ```gizlang const PIVOT_CELLS = 4096 ``` The most cells (row and column pairs) of a pivot.