# Data model

> Dimensions, dimension values, properties and bindings, value types with format, precision, limits and sensitivity, internal columns, line states, and how data is loaded and traced across the model.

A plan's data model consists of **dimensions**, their **properties**, and the **value types** that store measures over dimensions. All three are defined in the admin interface under *Datamodell* (Data model) or through the MCP server, and are visible in the external SQL views.

## Dimensions

A dimension (*dimension*) is a list of members — **dimension values** — each with a **code** and a **name**. Codes are the stable identifiers used in data, imports and Kex; names are for display.

| Example dimension | Example codes |
|---|---|
| `Account` | `3010`, `5010`, `7210` |
| `Department` | `D100`, `D200` |
| `Month` | `202601`, `202602` |
| `Scenario` | `Base`, `Upside` |

### Time as dimensions

The platform has no special time axis. Periods are ordinary dimensions such as `Month`, `Quarter` or `Year`, whose properties link them together (`Month.Quarter`, `Month.Year`) and carry calendar attributes. Properties such as a start or end month on a register entry are typically **bound to the period dimension** rather than stored as free dates. Period logic — "months from start to end", "open for planning" — is then expressed as joins and filters on dimension values.

### Dimension editor

The dimension editor has these side panels:

| Panel | Swedish label | Content |
|---|---|---|
| Properties | *Egenskaper* | The dimension's properties with IDs; bound properties are badged *Bunden till dimension* |
| Connections | *Kopplingar* | Which value types use selected dimension values, with clean-up operations — see [Tracing dimension values](#tracing-dimension-values) |
| Integration | *Integration* | Import configurations feeding the dimension; SQL export toggle and query |
| Details | *Detaljer* | ID, size (rows), display format (*Visa som*), value types using the dimension, history, description |

### Display formats

How a dimension value is shown — code, name or both — is set by a display format. The standard formats are:

| ID | Pattern | Example |
|---|---|---|
| 1 | `{Code} - {Name}` | `3010 - Sales` |
| 2 | `{Name} - {Code}` | `Sales - 3010` |
| 3 | `{Code}` | `3010` |
| 4 | `{Name}` | `Sales` |

The display format can be set on the dimension, overridden per dataset in an app (*Visa som*), and chosen per variable in actions. In Kex, `$formatted` returns the formatted text.

## Properties

A property (*egenskap*) adds a column to every value of a dimension. Properties are referenced in Kex as `Dimension.Property`, for example `Department.Region`.

- **Unbound properties** hold free values: text, numbers or dates.
- **Bound properties** hold values of another dimension. `Account.AccountGroup` bound to the dimension `AccountGroup` makes every account point to a member of that dimension. Bindings are how hierarchies, mappings and reporting structures are built. They are also how Kex joins value types that do not share a dimension directly (`include … on Account.AccountGroup`).
- **Multi-valued properties** hold several values separated by `;`. In Kex they are aggregated as a string by default and expanded to one row per value with `expand Dim.Prop`.

!!! warning "Bindings must not be circular"
    A property cannot be bound in a way that forms a cycle between dimensions. The same rule applies to calculations: the platform allows no cycles, either in model structure or in logic.

## Value types

A value type (*värdetyp*) stores one value column over a fixed set of dimensions. Each combination of dimension values holds at most one value.

| Setting | Meaning |
|---|---|
| ID and name | String ID used in Kex, e.g. `Amount`; display name |
| Dimensions | The value type's grain, e.g. `Account × Department × Month` |
| Format (*Format*) | Number, percentage, date, date-time or text |
| Display precision (*Decimalpresentation*) | Decimals shown, optionally hiding decimals when the value is zero |
| Entry precision (*Decimalinmatning*) | Decimals accepted and stored on entry |
| Value limits (*Värdegränser*) | Hard minimum and maximum: entries outside are rejected |
| Value warnings (*Värdevarningar*) | Soft lower and upper bounds: entries outside are warned about but accepted |
| Sensitive (`isSensitive`) | Hides the value, but not the row, from users without access to sensitive data |
| Description | Free text, also exposed to agents |

!!! note "What is shown is not what is stored"
    Display precision and entry precision are separate. A value type can accept five decimals and display none. Tables, exports and Kex always work with the stored value.

### Sensitive value types

A sensitive value type hides the **measure**, not the **row**. A user without access to sensitive data still sees which dimension combinations exist — for example, which employees have a salary row — but not the values. This allows roles such as a data administrator who maintains dimensions and runs imports without seeing salaries. See [Security](security.html).

### Changing a value type's dimensions

Dimensions can be added to or removed from a value type only when it is **empty of both plan data and reference data**. Emptying a value type also removes its **history**, and with it the basis for every point-in-time reference that reads that value type.

!!! warning "Irreversible"
    Emptying a value type to change its dimensions permanently removes its history. Point-in-time references to the value type will no longer return data for the period before the change. If the history matters, create a data reference first, or model the new grain as a new value type.

The order of a value type's dimensions can be changed at any time (*Ändra dimensions-sortering*). The order affects default presentation only.

### Value type panels

| Panel | Swedish label | Content |
|---|---|---|
| Dimensions | *Dimensioner* | The value type's grain and the change operation |
| Value columns | *Värdekolumner* | Format, precision, limits, warnings, sensitivity |
| Integration | *Integration* | Import configurations, SQL export toggle and query |
| Details | *Detaljer* | Lineage upstream (calculations writing the value type) and downstream (calculations and apps reading it) — see [Traceability](traceability.html) |

A view selector at the top of the value type switches between **plan data** and each **reference** of the plan. In reference view the data is read-only and the summary statistics are recalculated for the reference.

## Internal columns

Every row carries system columns, readable in Kex with `X.**` and in the SQL views.

| Column | On | Meaning |
|---|---|---|
| `$name`, `$formatted` | Dimension values | Name, and text formatted by the display format |
| `$edittime`, `$editby` | Both | Time of last change and who made it |
| `$edittype`, `$editid`, `$rowid` | Both | Change type, change ID and internal row ID |
| `$calcid` | Value types | ID of the calculation that wrote the row; empty for user-entered or imported rows. See [Parallel values](#parallel-values) |
| `$editstate` | Value types | Line state, see below |

### Parallel values

`$calcid` is a hidden system dimension on every value type. For one combination of dimension values, a value type can therefore hold several values side by side: one entered or imported value without a calculation ID, and one value per calculation that writes to it.

Every read sums them away: in apps, in exports, in Kex queries and when a calculation reads its sources. Use `expand X.$calcid` to see the parts, or `exclude calculated` to read only the non-calculated part.

## Line states

Each value-type row records how it came to exist. The app interface uses this to decide styling and editability.

| Code | State | Meaning |
|---|---|---|
| 0 | Suggested | Imported, or written by a suggestion calculation; a user may overwrite it |
| 5 | Zero placeholder | Created when a user edits a cell generated from initial values but the value remains empty or zero |
| 10 | Edited | Entered or changed by a user |
| 30 | Calculated | Written by a calculation |
| 40 | Initial value | Generated placeholder from a dataset's [initial values](datasets.html#initial-values) |

Rows written through import tools, the REST API or MCP get line state 0. Line state 10 is set by edits in the app interface.

Default [presentation rules](components.html) style suggested, read-only and calculated cells differently, so users can see where each number comes from.

## Loading data

Data reaches value types and dimensions through several routes. All of them follow the same import semantics.

| Route | Use | See |
|---|---|---|
| Import wizard on a value type or dimension | Ad-hoc file loads (CSV, TXT, xlsx) | below |
| Import configurations | Repeatable loads over files, storage or REST | [Data integration](integration.html) |
| App entry and actions | User input | [Apps](apps.html) |
| Calculations | Derived data | [Calculations](calculations.html) |
| MCP tools | Agent-driven loads and changes | [AI agents](ai-agents.html) |

### Import wizard

The wizard on a value type (*Importera*) has three steps:

1. **Import type.** *Full import* adds new rows and updates existing ones. *Endast ny data* (only new) adds rows but updates none. *Endast uppdatering* (only update) updates existing rows but adds none.
2. **Column mapping.** Map file columns to dimensions and the value column, with a preview. The writing calculation (`$calcid`) cannot be mapped: lineage can be read but not imported.
3. **Settings.**
    - Choose how duplicate rows with the same dimension values are handled: sum, average, min, max, or fail.
    - Choose whether unknown codes create new dimension values (*Skapa nya dimensionsvärden*).

An export from a value type can be imported again as-is.

## Tracing dimension values

The **Connections** panel (*Kopplingar*) on a dimension shows, for selected dimension values, every value type in which they occur. From there you can remove the selected values' data from one value type, from a chosen subset in the advanced view, or from all value types.

!!! warning "History is retained"
    Removing data through *Kopplingar* removes it from the current state of the value types. Earlier versions remain in [history](references-history.html#history) and can still be read through point-in-time references and `from history`.

!!! agent "Pitfalls for agents"
    Pitfalls around identifiers, changing dimensions, creating dimension values on import and sensitive value types are in the [Agent guide](agent-pitfalls.html#data-model).

## Related

- [Core concepts](concepts.html)
- [References and history](references-history.html)
- [Traceability](traceability.html)
- [Data integration](integration.html)
- [Datasets](datasets.html)
