> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/datasets/dataset-versions-and-history.md).

# Dataset versions and history

Versioning turns a mutable working cohort into a reproducible input. The version—not the display name alone—belongs in project, automation, and release records.

### Before you make the change

* Reconcile membership count and source provenance.
* Inspect representative grouped and ungrouped items.
* Write a concise version note that explains the reason for change.

### Follow the interface

#### Select an explicit published version

![Dataset detail with the version selector open](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FFK9u4LCEb09b3EpcNHrr%2Fdataset-version-selector.png?alt=media\&token=1acc72b5-e11b-4e48-95fc-d5a7bda33ca0)

*Open a dataset and choose the current version badge. The selector shows the latest marker, version number, publication reason, item count, date, and a route to the complete history.*

#### Review the complete membership history

![Dataset history dialog showing version deltas and actions](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FVlkSuopZNbC9JUP9uVx1%2Fdataset-history.png?alt=media\&token=27ae53b7-17d1-45dc-a93b-200509328987)

*View all versions opens Dataset history. Expand a version to inspect who published it, its timestamp, item delta, activity, View version, and Duplicate as new dataset actions.*

### Understand the product behavior

The SDK describes datasets as version-first:

1. Create a dataset from selected folders or assets.
2. Make edits, which appear as unpublished changes.
3. Publish a named version to freeze a snapshot.
4. Attach the latest or an exact version to a project.

This distinction prevents a project from silently changing when someone adds new assets to the working dataset. An exact attachment can reference, for example, dataset version 2 rather than “whatever the dataset contains today.”

The current model is:

```
Folders and assets
        ↓
Mutable dataset working draft
        ↓ Publish version
Immutable DatasetVersion
        ↓ Attach
Independent project copy
```

There is no **Sync**, **Ignore**, or **Auto-Sync** action between a project and an attached Data Assets source. Editing the source after attachment does not alter the project. To adopt the change, the user publishes a newer dataset version and attaches that version.

### Datasets-list UX

The standalone Datasets page includes search, **New Dataset**, Active/Archived/Trash views, pagination, row selection, and a table with:

* Name;
* Version;
* Assets;
* Size;
* Data Type;
* Used in;
* Last Modified;
* Created By;
* Actions.

The Version cell is an orange **Draft vN** pill when publishing would create the next version, or a blue **vN** pill when the working draft matches the latest published version. Mixed-family datasets display **Multimodal**.

Row actions adapt to lifecycle state. Active datasets can be renamed, have files added, attach a published version to a project, archive, or move to Trash. Archived datasets can be restored to Active or trashed. Trash supports Restore or Delete forever. Dataset lifecycle changes affect the dataset and its versions/memberships; they do not archive or delete the underlying folders and assets.

### Create a dataset

1. The user selects **New Dataset**.
2. The user enters a name and optional description.
3. The user chooses at least one folder or asset from the lazy-loaded, server-searched source picker.
4. Unitlab creates the mutable working draft.
5. The dataset detail page opens with its folders and assets.
6. The user publishes v1 before the dataset can be attached to a project.

Adding files to an existing dataset adds existing workspace folders/assets to the working draft. It is not an upload-directly-into-dataset operation.

### Dataset detail and history

The default detail view is the live working draft. It includes a version dropdown, Grid/List browsing, **Publish version** when changes exist, and **Attach Data** for adding sources to the draft.

Selecting a published version opens a read-only snapshot. It preserves the frozen folder hierarchy, shows a **Read only** chip, and provides **Back to current**. No mutation or publish action appears in snapshot mode.

**View all versions** opens the single history modal. It contains the current working-draft card when dirty and one expandable card per published version. Available actions include:

* View version;
* Restore to working draft;
* Duplicate as new dataset.

Restore changes the working draft and requires a later Publish version action; it never creates a version immediately. Restore is unavailable for live-source-backed own-data or folder-tracking datasets because their draft follows the underlying source.

Changes that can trigger the Draft pill include adding/removing files, folder moves, renames, tag changes, and relevant dataset-name changes—not only item count.

### Operate published membership

{% stepper %}
{% step %}

#### 1. Open the dataset

From Data Space › Datasets, open the dataset name to reach its asset view.
{% endstep %}

{% step %}

#### 2. Inspect the active version

Open the version badge and verify latest status, publication reason, item count, and date.
{% endstep %}

{% step %}

#### 3. Open Dataset history

Choose View all versions to compare version-level counts, publishers, timestamps, and additions or removals.
{% endstep %}

{% step %}

#### 4. Inspect or duplicate a version

Use View version for read-only membership inspection or Duplicate as new dataset when a new lineage must begin from that snapshot.
{% endstep %}

{% step %}

#### 5. Use the explicit version

Attach or automate against the intended version ID; do not rely on the display name or whichever version is latest today.
{% endstep %}

{% step %}

#### 6. Treat membership change as history

Add or remove approved content through the dataset workflow so the change produces a new auditable version.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision         | Production guidance                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| Version scheme   | Choose a scheme the team can advance consistently and interpret in audit records.                   |
| Change note      | State what changed and why, not only who clicked publish.                                           |
| Project behavior | Confirm whether an attached project follows a selected version or requires deliberate reattachment. |
| Recovery         | Know how to restore or duplicate a prior usable state without deleting evidence.                    |

### Continue the operating flow

* Attach the published version to the intended project.
* Record its ID in release provenance.
* Review history before any membership correction.