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

# How Atoti manages data versioning

> How Atoti manages data versioning using versions, epochs, and branches in the in-memory datastore, and how DirectQuery versioning depends on external database time-travel support and manual refresh.

Data versioning helps manage multiple states of data for comparison and simulation.
A new version of the data is created each time data is loaded, inserted, or deleted.
Data versioning is implemented differently depending on whether you use the Atoti datastore or access an external database using DirectQuery.

* Atoti in-memory datastore natively manages data versioning
* With DirectQuery, data versioning is dependent on the external database's native support.

## What is a version?

A version represents a snapshot of the available data at a specific point in time.
Versions allow you to access data from different points in time.

## What is an epoch?

An epoch is a point-in-time marker within a version.\
It tracks incremental changes applied to a version. Epochs allow you to:

* Roll back to a previous state.
* Audit changes over time.

Each version maintains its own sequence of epochs.

## What is a branch?

A branch contains several versions of the data that can evolve independently.
Branches are useful for performing simulations:

* Testing changes without impacting the original version.
* Creating alternative scenarios.
* Performing What-if analysis.

Branches inherit data from their parent version but can diverge as new data is added.

## Versioning in the Atoti datastore

When data resides in the Atoti Datastore, versioning is provided natively by Atoti.

* Each committed transaction creates a new version of the datastore. The new version can be queried.
* Epochs record incremental changes within versions for auditing and rollback.
* Branches are fully supported and provide an isolated workspace for simulations without affecting the main data.
* Branches can be compared directly with the base version or with other branches to evaluate the impact of changes, forming the basis of Atoti’s what‑if analysis.

## Related reading

Find out more about data versioning and the Atoti datatstore by following these links:

* [Atoti Java SDK](/engine/java-sdk/latest/concepts/data_versioning)

## Versioning with DirectQuery

With DirectQuery, Atoti reads data directly from an external database and maintains internal snapshots to support hierarchies and aggregates. Versioning capabilities depend on the external system:

* If the external database supports native time travel, Atoti can query historical snapshots.
* If the external database does not support native time travel, only the latest snapshot is available.

External databases cannot push change events to Atoti, so users must explicitly trigger refreshes.
This is managed by the DirectQuery connector.
When an external database changes, some cube components (hierarchies, aggregate providers) can become temporarily out of sync until a refresh is performed.

## Further reading

For an introduction to [DirectQuery](../load-data/DirectQuery.md) read this page.

Keep DirectQuery data up to date using Atoti Java SDK:

* **Incremental refresh**: A specific scope of data is updated.
* **Full refresh**: All the data from the external database is updated.

DirectQuery does not support branches. Any simulations that require branches must use the Datastore.

## Summary: Datastore vs. DirectQuery

| Capability                       | Datastore                                 | DirectQuery                                                            |
| -------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
| Historical versions available    | ✔️ Natively provides consistent snapshots | ✔️ Only if external DB supports time travel; otherwise latest snapshot |
| Epochs within versions           | ✔️ Fully supported                        | ⚠️ Behavior depends on external DB’s capabilities                      |
| Branches for simulations         | ✔️ Fully supported                        | ❌ Not supported                                                        |
| How changes are ingested         | Automatic via transactions                | User‑triggered Incremental or full refresh                             |
| Cube availability during updates | ✔️ Yes                                    | ✔️ Yes (during both incremental and full refresh)                      |
| Risk of desynchronization        | Low                                       | Medium for non‑time‑travel databases until refresh completes           |