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

# Datasets

> First-class Postgres datasets: one managed Postgres database per dataset, editable as tables in the console and forked per redteam conversation.

Datasets are first-class in Gradient, and they are just Postgres. A dataset is the world your agent's tools read and write while you test it: the patients and appointments, orders and accounts, that a scenario needs in order to be true.

<Note>
  Datasets are the relational world behind [redteam testing](/evaluate/redteam). A [scenario](/evaluate/rubrics) is reproducible only because it binds to specific rows in one.
</Note>

## One Postgres project per org, one database per dataset

Each organization gets its own managed Postgres project. Each dataset is a full Postgres database inside that project: ordinary tables, columns, rows, and SQL, with nothing Gradient-specific bolted on.

```mermaid theme={null}
flowchart TD
    O["Organization"] --> P["Postgres project"]
    P --> D1["Dataset<br/>Postgres database"]
    P --> D2["Dataset<br/>Postgres database"]
    D1 --> S["Snapshot<br/>pinned point in history"]
    S --> F1["Fork<br/>one redteam conversation"]
    S --> F2["Fork<br/>one redteam conversation"]
```

A new dataset provisions in the background and flips from **provisioning** to **ready** once its database exists.

## Edit it as a table, or drop into SQL

The **Datasets** tab is table-first. Open a dataset and you get four views:

<Tabs>
  <Tab title="Tables">
    Browse every table, create tables, add, rename, and drop columns, and insert, edit, and delete rows: the point-and-click path for shaping fixtures.
  </Tab>

  <Tab title="SQL">
    Run arbitrary SQL against the dataset. This is the fast path for seeding, bulk edits, and the joins a coding agent writes when it authors a scenario.
  </Tab>

  <Tab title="Snapshots">
    Immutable versions pinned at a single point in the dataset's history (below).
  </Tab>

  <Tab title="Forks">
    The per-conversation branches that redteam runs create (below).
  </Tab>
</Tabs>

A branch selector switches the **Tables** and **SQL** views between **main** and any active fork, so you can inspect exactly what one redteam conversation did to its own copy.

## Snapshots pin a point in time

A snapshot records a single, immutable point in the dataset's history. Snapshots are numbered (`v1`, `v2`, and so on). Because a snapshot is an exact position, every fork taken from it starts from the same known state, which is what makes a redteam run reproducible from one day to the next.

## Forks are writable, per-conversation copies

When a redteam conversation starts, Gradient forks a writable branch of the dataset, from **main** or from a snapshot you pin. That fork is the world the conversation's tools actually read and write:

* The fork's connection string is provided to your tool at runtime, so your handlers hit the fork, never production.
* Tool calls **persist** inside the conversation: an `INSERT` from one turn is visible to the next. That is what makes multi-step scenarios testable at all.
* Forks are short-lived. Each is reclaimed when its conversation ends, and swept automatically if one is ever left behind, so many conversations can run in parallel, each on its own copy.

<Warning>
  The isolation runs both ways. A redteam fork can never reach the tenant database, and production traffic can never be routed to a fork: the fork is bound to authenticated redteam context, not a flag a caller can set.
</Warning>

## A scenario binds to specific rows

"Existing patient with a previous appointment" means nothing without an existing patient and a previous appointment. A [scenario](/evaluate/rubrics) binds to specific rows: this patient, that prior appointment, this doctor at that location. The binding is what makes the scenario reproducible and its rules checkable: "looked up the existing record" is verifiable because there is a specific record to look up.

To drive a failure path, bind different rows (a patient last seen four years ago, an appointment already cancelled) instead of writing a special mock.

<CardGroup cols={2}>
  <Card title="Redteam testing" icon="vial" href="/evaluate/redteam">
    Run the production agent against a fork of a seeded dataset.
  </Card>

  <Card title="Rubrics, scenarios, and rules" icon="list-check" href="/evaluate/rubrics">
    Bind a scenario to rows and grade what the agent did with them.
  </Card>
</CardGroup>