> **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.

# Datasets

A dataset is a named, versioned collection of [tables](/get-started/concepts/tables). It's what you work with in Amp:
you register a dataset to publish it, deploy it to fill its tables with data, and query its tables with SQL. Datasets
behave like software packages: they have versions, other datasets depend on them, and you can share them.

Datasets are referenced as `namespace/name@revision`, like `acme/eth_mainnet@1.0.0`.

## Kinds of datasets

Each dataset has a kind, which says where its data comes from.

### Raw datasets

A [raw dataset](/datasets/raw-datasets) extracts one chain's data, like Ethereum mainnet's blocks, transactions, and
logs. Its kind is the kind of chain data it reads, like `evm-rpc` for Ethereum and other EVM chains, or `solana`. Each
kind has a fixed set of [tables](/datasets/tables/evm-rpc).

A raw dataset doesn't say where to get the data: it names a kind and a network, and Amp extracts it through a
[provider](/get-started/concepts/providers) with the same kind and network. It also has a start block, the first block
it covers.

### Derived datasets

A [derived dataset](/datasets/derived-datasets) computes its tables with SQL over other datasets, its dependencies. It's
how you turn raw chain data into what your application needs: decoded token transfers, swaps, balances, or data joined
across chains. Its kind is `manifest`.

Amp keeps derived tables up to date: as its dependencies get new blocks, it runs the SQL over them, and adds the
results.

### Static datasets (In development)

A [static dataset](/datasets/static-datasets) serves CSV files as tables, for reference data that doesn't come from a
chain, like labels for addresses. Its kind is `static`. It has no blocks, and nothing to extract: you register it, then
query it.

## Manifests

A dataset is defined by its [manifest](/datasets/manifests): a JSON document that declares its kind, its tables and
their columns, and what its kind needs, like a raw dataset's network and start block, or a derived dataset's
dependencies and SQL. `ampctl manifest generate` writes a raw dataset's manifest for you. This one starts like this:

```json [eth_mainnet.json]
{
  "kind": "evm-rpc",
  "network": "mainnet",
  "start_block": 24000000,
  "finalized_blocks_only": false,
  "tables": {
    "blocks": {
      "schema": {
        "arrow": {
          "fields": [
            { "name": "_block_num", "type": "UInt64", "nullable": false },
            …
```

You write derived and static manifests yourself. The [Manifest Reference](/datasets/manifest-reference) documents every
field.

A manifest's hash, a 64-character fingerprint of its contents, identifies it: change anything in a manifest, and its
hash changes. Amp stores manifests by hash, so the same hash always means the same definition.

## Names and namespaces

A dataset's name has two parts, `namespace/name`:

* The **namespace** groups datasets, by organization, team, or project, like `edgeandnode` or `acme`. On a hosted Amp,
  namespaces also decide who can read and publish which datasets. `_` is the default namespace.
* The **name** identifies the dataset in its namespace, like `eth_mainnet`.

In SQL, a table is its dataset's name in double quotes, then the table's name: `"acme/eth_mainnet".blocks`. The quotes
are needed because of the `/`.

## Revisions

A dataset has versions, and a reference picks one with its revision, after the `@`:

| Revision                                 | Example                          | What it selects                                     |
| ---------------------------------------- | -------------------------------- | --------------------------------------------------- |
| A [semantic version](https://semver.org) | `acme/eth_mainnet@1.0.0`         | The version you tagged with that number             |
| `latest`                                 | `acme/eth_mainnet@latest`        | The highest semantic version                        |
| `dev`                                    | `acme/eth_mainnet@dev`           | The version registered most recently, tagged or not |
| A manifest hash                          | `acme/eth_mainnet@b9e2ebd92c07…` | That exact manifest, which never changes            |

Without a revision, a reference means `latest`: `"acme/eth_mainnet".blocks` queries the highest semantic version.

Semantic versions, `latest`, and `dev` are tags: names that point to a manifest hash, and can move. You set semantic
versions when you register a dataset; Amp moves `latest` and `dev` itself. Amp resolves every reference to a hash
before it uses it, so a deployment or a dependency never changes under you. Use a hash when something must keep using
the exact same definition, like a reproducible report.

Several versions of a dataset can exist, and be queried, side by side. Each has the tables and columns its own manifest
declares. [Versioning](/datasets/versioning) explains tags in detail.

## Register, deploy, query

A dataset goes through three steps:

1. **Register**: `ampctl dataset register` stores the manifest, gives it a name, and moves its tags. Without `--tag`,
   it moves only `dev`; with `--tag 1.0.0`, it also creates version `1.0.0`, and moves `latest` if that's now the
   highest version. Registering extracts nothing. A derived dataset's dependencies must be registered first.
2. **Deploy**: `ampctl dataset deploy` starts filling a version's tables. Amp schedules a
   [job](/get-started/concepts/jobs-and-workers), and a worker extracts the data, or runs the SQL, block after block.
   Static datasets are never deployed.
3. **Query**: query the tables with SQL, while they fill and after.

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

:::tip
A dataset is only a definition. Whether it follows the chain forever or stops at a given block is decided when you
deploy it, with `--end-block`, not in the dataset itself.
:::

The [Quickstart](/get-started/quickstart) goes through all three, and [Managing Datasets](/managing-amp/datasets)
covers everything else you can do with them.