> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset versioning

> Datasets change. Track versions so simulation results stay comparable.

Datasets evolve — you add examples, edit annotations, refine tags. If simulation results are pinned to specific dataset states, results stay comparable over time even as the dataset grows.

## How versioning works

Every "significant" change to a dataset creates a new version:

* Add examples.
* Delete examples.
* Edit an annotation.
* Split into a holdout.

Metadata edits (renaming, tagging) don't create versions.

Versions are numbered (v1, v2, ...) and stamped with actor, timestamp, and change summary.

## Pinning simulations to versions

Every simulation run records the dataset version it used. When you compare two runs:

* If they used the same dataset version, results are directly comparable.
* If they used different versions, Nora shows the diff (added/removed/changed examples) so you understand the drift.

You can force a simulation to a specific dataset version (default: latest).

## The version history

Datasets → **Versions** tab. Shows:

* Each version's number, timestamp, author.
* Change summary (X examples added, Y annotations edited).
* Which simulations used this version.
* Which Improvements are gated on this version.

Click any version to see the state at that point. Roll back to a prior version if a bad edit was applied.

## When to bump vs. edit in place

Bumping happens automatically on significant changes. But for finer-grained control:

* **Force new version** — before a period of many changes, snapshot the current state so you always have a reference point.
* **Edit in place (patch)** — for typo fixes and minor annotation clarifications that shouldn't invalidate prior simulations. Use sparingly.

## Cross-referencing with Flow versions

The Improvement flow shows a matrix: Flow versions × Dataset versions. Each cell has the simulation result. Useful for questions like:

* "Which Flow version scored best on the current dataset?"
* "Has the same Flow version's score changed as the dataset grew?"

Both dimensions matter — a Flow that scores well on a small dataset might struggle on a bigger, more diverse one.

## Immutability

Simulation results are immutable and tied to specific dataset + Flow versions. This means:

* Old results stay valid even if you retire the dataset version.
* You can trust historical comparisons — the numbers weren't recomputed with new data.

## Deleting a version

Versions are permanent. You can archive a version (hides it from the default view) but you cannot delete — this would invalidate any simulation that used it.

If storage is a concern, versions can be **compacted** — the full state is stored only for milestone versions; intermediate versions are stored as diffs. Runs still work; older intermediate versions just take slightly longer to load.

## Export / import

Any version can be exported as JSONL (`nora datasets export <slug>@v3 > snapshot.jsonl`) and re-imported into another workspace. Useful for sharing datasets across environments (staging → prod, or between teams).