> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# Versioning

A dataset changes over time: you add a table, fix a query, or extract from a later block. Versions let you publish
those changes without breaking anyone who relies on an earlier definition. Each version of a dataset points to one
[manifest](/datasets/manifests), which never changes, and several versions can be queried side by side.

## Dataset references

You refer to a dataset as `namespace/name@revision`, like `acme/eth_mainnet@1.0.0`:

* **Namespace**: who the dataset belongs to, like your team or organization: `acme`, or `_`, the default namespace.
* **Name**: the dataset's name, like `eth_mainnet`.
* **Revision**: which version, after `@`. It's one of:

| Revision        | Example                     | Points to                                                                                   |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------- |
| A version       | `1.0.0`, `2.1.3-alpha.1`    | The manifest you tagged with it. Versions follow [semantic versioning](https://semver.org). |
| A manifest hash | `b9e2ebd9…` (64 characters) | That exact manifest.                                                                        |
| `latest`        | `latest`                    | The highest version.                                                                        |
| `dev`           | `dev`                       | The manifest you registered last, tagged or not.                                            |

Amp turns a revision into a manifest hash each time it reads it. Jobs and queries then run against that one manifest.

## Register versions

Registering a manifest without `--tag` makes it the dataset's `dev` revision. Use it while you iterate:

```bash
ampctl dataset register acme/eth_mainnet ./eth_mainnet.json
```

Registering with `--tag` also tags the manifest with that version, for others to use. When it's the highest version,
`latest` moves to it:

```bash
ampctl dataset register acme/eth_mainnet ./eth_mainnet.json --tag 1.0.0
```

You can't tag `latest` or `dev` yourself: Amp moves them.

:::warning
Registering another manifest with a version that already exists moves that version to it, without warning. To be sure
a reference never changes, use the manifest's hash.
:::

### How `latest` and `dev` move

This sequence registers three manifests, A, B, and C, for one dataset:

| Command                           | Versions                        | `latest` | `dev` |
| --------------------------------- | ------------------------------- | -------- | ----- |
| `register … ./a.json`             | none                            | none     | A     |
| `register … ./a.json --tag 1.0.0` | 1.0.0 → A                       | 1.0.0    | A     |
| `register … ./b.json`             | 1.0.0 → A                       | 1.0.0    | B     |
| `register … ./b.json --tag 1.1.0` | 1.0.0 → A, 1.1.0 → B            | 1.1.0    | B     |
| `register … ./c.json --tag 0.9.0` | 0.9.0 → C, 1.0.0 → A, 1.1.0 → B | 1.1.0    | C     |

`dev` always moves to the manifest you registered last. `latest` only moves to a version higher than the current one.

### Tag a manifest by its hash

To tag a manifest that's already registered, give its hash instead of a file. This also adds it to another dataset:

```bash
ampctl dataset register acme/eth_mainnet b9e2ebd92c0752ba8a61a233f9cc5d3f4f8b601b1b789a882a5dd8ece9bca56b --tag 1.0.1
```

## List versions

:::terminal
```bash
ampctl dataset versions acme/eth_mainnet
```

```
Dataset: acme/eth_mainnet

Latest version: 1.0.0
Dev hash: b9e2ebd92c0752ba8a61a233f9cc5d3f4f8b601b1b789a882a5dd8ece9bca56b

Versions:
  1.0.0 (b9e2ebd92c0752ba8a61a233f9cc5d3f4f8b601b1b789a882a5dd8ece9bca56b)
    Created: 2026-11-02T17:43:11.748176+00:00
    Updated: 2026-11-02T17:43:11.748176+00:00
```
:::

`ampctl dataset inspect` shows one revision, and which tags point to it:

:::terminal
```bash
ampctl dataset inspect acme/eth_mainnet@latest
```

```
Namespace:             acme
Name:                  eth_mainnet
Revision:              1.0.0, latest, dev
Kind:                  evm-rpc
Manifest Hash:         b9e2ebd92c0752ba8a61a233f9cc5d3f4f8b601b1b789a882a5dd8ece9bca56b
Start Block:           24000000
Finalized Blocks Only: false
Tables:                blocks, logs, transactions
```
:::

## Choose a revision

Which revision to use depends on how much change you accept:

* **A version**, like `@1.0.0`, for deployments, automation, and sharing. It only changes if someone tags another
  manifest with it.
* **A manifest hash** when a definition must never change: reproducible jobs, audits, and other systems that must keep
  reading the same data. [Derived datasets](/datasets/derived-datasets#dependencies) name their dependencies by version
  or hash only.
* **`latest`** to follow releases: a deployment or query of `@latest` uses the highest version at the time.
* **`dev`** while you work on a dataset.

## Query versions

In SQL, quote a dataset's reference, since it contains a `/`. Without a revision, a query reads `latest`:

```sql
SELECT block_num, gas_used FROM "acme/eth_mainnet".blocks
```

With one, it reads that revision. Versions can be queried together, like any tables:

```sql
SELECT block_num, gas_used FROM "acme/gas@1.0.0".block_gas
UNION ALL
SELECT block_num, gas_used FROM "acme/gas@1.1.0".block_gas
```

Each version has the tables and columns its own manifest declares. When you query several, select columns each of
them has, with the same types.

A query reads a symbolic revision (`latest`, `dev`) when it starts. Over Arrow Flight, Amp reads it once to describe
the query's results and again to run it, so a version released in between changes what the query reads. To rule
that out, name a version or a hash, in the SQL or with a [dataset alias](/querying/dataset-aliases).

## Limitations

* `latest` only exists once you've tagged a version, and `dev` once you've registered a manifest.
* Removing a version tag doesn't delete its manifest: other versions and datasets can still use it.
* A manifest can be stored on its own, by its hash, without belonging to a dataset (see
  [Manifest Storage](/managing-amp/manifests)). It needs to be added to a dataset before you can tag it or refer to
  it by the dataset's name.