# 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<string>; fields: Vec<Typed.Contract>; }
```

A dataset of the model: its declaration, table, grain (the columns that make a row unique) and fields.

- `declaration`: `string`
- `table`: `string`
- `grain`: `Vec<string>`
- `fields`: `Vec<M54.Contract>`

### `Relationship`

```gizlang
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`: `string`
- `many`: `string`
- `one`: `string`
- `foreign`: `Vec<string>`
- `primary`: `Vec<string>`

### `Meaning`

```gizlang
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`: `string`
- `unit`: `string`
- `currency`: `string`
- `calendar`: `string`
- `additive`: `Vec<string>`

### `Metric`

```gizlang
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`: `string`
- `dataset`: `string`
- `meaning`: `M53.Meaning`
- `dependencies`: `Vec<string>`
- `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<Dimension>; }
```

Units name normalized products of physical dimensions. Conversion is an
explicit calculation; matching dimensions never silently rescales a value.

- `declaration`: `string`
- `dimensions`: `Vec<M53.Dimension>`

### `Model`

```gizlang
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<M53.Dataset>`
- `relationships`: `Vec<M53.Relationship>`
- `metrics`: `Vec<M53.Metric>`
- `schemas`: `Vec<M55.Schema>`
- `units`: `Vec<M53.Unit>`
- `fields`: `Vec<M53.Meaning>`

### `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<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`: `M53.Pivot`
- `measure`: `string`
- `rowKeys`: `Vec<M55.Value>`
- `columnKeys`: `Vec<M55.Value>`
- `cells`: `Vec<_gizlang_sdk_core.Option<M55.Value>>`
- `rowTotals`: `Vec<M55.Value>`
- `columnTotals`: `Vec<M55.Value>`
- `total`: `_gizlang_sdk_core.Option<M55.Value>`

### `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<Observed>; }
```

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<M53.Observed>`

## Functions

### `dimensions`

```gizlang
function dimensions(input: Vec<Dimension>): Result<Vec<Dimension>, DbError>
```

A bounded canonical exponent vector is the sole unit algebra.

Effects: fail.

### `product`

```gizlang
function product(left: Vec<Dimension>, right: Vec<Dimension>, divide: bool): Result<Vec<Dimension>, 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<bool, DbError>
```

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<string>): Result<bool, DbError>
```

SUM across a one-to-many join cannot silently multiply the fact grain.

Effects: fail.

### `certified`

```gizlang
function certified<P, R>(model: Model, metric: Metric, query: Query.Prepared<P, R>, rollup: Vec<string>): Result<Query.Prepared<P, R>, 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<Typed.Slot>, rows: Vec<Vec<Value>>): Result<Crosstab, DbError>
```

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<Typed.Slot>, outputs: Vec<Typed.Slot>): Result<bytes, DbError>
```

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<Typed.Slot>, outputs: Vec<Typed.Slot>, revision: i64, publisher: string): Result<Certificate, DbError>
```

The certificate of METRIC of MODEL with its PARAMETERS and OUTPUTS, at REVISION, by PUBLISHER.

Effects: fail.

### `certificateRecord`

```gizlang
function certificateRecord(receipt: Certificate): Result<string, DbError>
```

The certificate as its encoded record.

Effects: fail.

### `readCertificate`

```gizlang
function readCertificate(payload: string): Result<Certificate, DbError>
```

The certificate of an encoded record. It fails when the record is not valid.

Effects: fail.

### `meaningDigest`

```gizlang
function meaningDigest(metric: Metric): Result<bytes, DbError>
```

Meaning, policy and display hashes deliberately have independent dependency sets.

Effects: fail.

### `definitionDigest`

```gizlang
function definitionDigest(model: Model, metric: Metric): Result<bytes, DbError>
```

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<Display>): bytes
```

The digest of the display settings, which a certificate keeps.

Effects: fail.

### `metricRecord`

```gizlang
function metricRecord(model: Model, metric: Metric): Result<string, DbError>
```

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.

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<string>; fields: Vec<Typed.Contract>; }

A dataset of the model: its declaration, table, grain (the columns that make a row unique) and fields.

declaration: string
table: string
grain: Vec<string>
fields: Vec<M54.Contract>

`Relationship`

gizlang

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: string
many: string
one: string
foreign: Vec<string>
primary: Vec<string>

`Meaning`

gizlang

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: string
unit: string
currency: string
calendar: string
additive: Vec<string>

`Metric`

gizlang

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: string
dataset: string
meaning: M53.Meaning
dependencies: Vec<string>
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<Dimension>; }

Units name normalized products of physical dimensions. Conversion is an explicit calculation; matching dimensions never silently rescales a value.

declaration: string
dimensions: Vec<M53.Dimension>

`Model`

gizlang

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<M53.Dataset>
relationships: Vec<M53.Relationship>
metrics: Vec<M53.Metric>
schemas: Vec<M55.Schema>
units: Vec<M53.Unit>
fields: Vec<M53.Meaning>

`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<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: M53.Pivot
measure: string
rowKeys: Vec<M55.Value>
columnKeys: Vec<M55.Value>
cells: Vec<_gizlang_sdk_core.Option<M55.Value>>
rowTotals: Vec<M55.Value>
columnTotals: Vec<M55.Value>
total: _gizlang_sdk_core.Option<M55.Value>

`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<Observed>; }

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<M53.Observed>

Functions

`dimensions`

gizlang

function dimensions(input: Vec<Dimension>): Result<Vec<Dimension>, DbError>

A bounded canonical exponent vector is the sole unit algebra.

Effects: fail.

`product`

gizlang

function product(left: Vec<Dimension>, right: Vec<Dimension>, divide: bool): Result<Vec<Dimension>, 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<bool, DbError>

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<string>): Result<bool, DbError>

SUM across a one-to-many join cannot silently multiply the fact grain.

Effects: fail.

`certified`

gizlang

function certified<P, R>(model: Model, metric: Metric, query: Query.Prepared<P, R>, rollup: Vec<string>): Result<Query.Prepared<P, R>, 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<Typed.Slot>, rows: Vec<Vec<Value>>): Result<Crosstab, DbError>

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<Typed.Slot>, outputs: Vec<Typed.Slot>): Result<bytes, DbError>

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<Typed.Slot>, outputs: Vec<Typed.Slot>, revision: i64, publisher: string): Result<Certificate, DbError>

The certificate of METRIC of MODEL with its PARAMETERS and OUTPUTS, at REVISION, by PUBLISHER.

Effects: fail.

`certificateRecord`

gizlang

function certificateRecord(receipt: Certificate): Result<string, DbError>

The certificate as its encoded record.

Effects: fail.

`readCertificate`

gizlang

function readCertificate(payload: string): Result<Certificate, DbError>

The certificate of an encoded record. It fails when the record is not valid.

Effects: fail.

`meaningDigest`

gizlang

function meaningDigest(metric: Metric): Result<bytes, DbError>

Meaning, policy and display hashes deliberately have independent dependency sets.

Effects: fail.

`definitionDigest`

gizlang

function definitionDigest(model: Model, metric: Metric): Result<bytes, DbError>

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<Display>): bytes

The digest of the display settings, which a certificate keeps.

Effects: fail.

`metricRecord`

gizlang

function metricRecord(model: Model, metric: Metric): Result<string, DbError>

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.