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

# Save and reuse datasets

> Give each Tool reusable starting records, choose them for scenarios, and reset an idle connection to a saved version.

A dataset is a named set of synthetic records for one Tool. You can reuse it
across scenarios or give two copies of the same Tool different starting data.
Datasets are optional: the Tool's existing starting data still works without one.

## Save starting records

Open your Tool setup's source draft and its **Saved datasets** section. Choose
the Tool copy, enter a name and supply records grouped by collection. Publish
the exact draft revision first if its Tool contracts have not been compiled.

This example illustrates the file shape, not a schema that every Tool accepts:

```json theme={null}
[
  {
    "namespace": "requests",
    "records": [
      { "rowId": "request-1", "value": { "title": "Synthetic request" } }
    ]
  }
]
```

Use collection names and record properties from the selected Tool's schema.
Saving validates the records and creates an immutable dataset version. It does
not change your source draft or any running connection.

From the CLI, set `PROJECT_ID`, `DRAFT_ID`, `TOOL_ID` and `COPY_ID` to the actual
IDs in your project. Save the collections above, adapted to your Tool's schema,
in `collections.json`:

```sh theme={null}
firedrill data save --project "$PROJECT_ID" --draft "$DRAFT_ID" \
  --tool "$TOOL_ID" --instance "$COPY_ID" \
  --collections collections.json --name "Busy starting state" \
  --idempotency-key save-busy-data-001 --json
```

For a legacy source with no named copies, omit `--instance`. Never guess a copy
ID. `--setup` also accepts a ready saved setup, but remains pinned to that setup's
original source; use `--draft` after publishing a newer draft revision.

## Choose data for a scenario

Select a dataset version for each Tool copy you want to change. Choose whether
to apply the selections to the baseline or a named scenario, then review and
apply them. Publish and review the resulting source revision before using it.

Each selection replaces **all collections in that Tool copy**. Omitted
collections become empty; they do not inherit old records. Other copies stay
unchanged. An empty dataset is a valid choice.

For a scenario, the dataset supplies starting records **before** that scenario's
authored actions. Those actions can subsequently change or delete the records.
Applying another selection replaces the previously generated starting-data
prefix rather than stacking copies of it.

CLI selection files contain the exact IDs, revision and digest returned by
`data show`; they contain no record values:

```json theme={null}
[
  {
    "packageId": "your-tool-id",
    "instanceId": "your-copy-id",
    "datasetId": "dataset-id-from-save",
    "revision": 1,
    "digest": "digest-from-data-show"
  }
]
```

Replace every illustrative value with the returned value, save as
`selection.json`, then apply:

```sh theme={null}
firedrill data apply --project "$PROJECT_ID" --draft "$DRAFT_ID" \
  --selection selection.json --target scenario --scenario "$SCENARIO_ID" \
  --idempotency-key apply-busy-data-001 --json
```

Use `--target baseline` without `--scenario` for default starting data.
Simulations, saved tests and CI use the exact published data in their selected
source version. Updating a dataset later cannot change a queued plan, an old
result or an already-running connection.

## Reset to a saved version

In an idle Tool connection, choose **Reset**, then **Saved dataset** and select
the exact Tool copies and versions. Review the affected copies and confirm.
Completion means the operation has finished, not merely that it was accepted.

CLI reset accepts the same selection array as JSON. It requires named copies:

```sh theme={null}
SELECTION_JSON="$(jq -c . selection.json)"
firedrill session reset --project "$PROJECT_ID" --session "$SESSION_ID" \
  --datasets "$SELECTION_JSON" --confirm "$SESSION_ID" \
  --idempotency-key reset-busy-data-001 --json
```

Reset replaces the selected copies' records and resets their associated Tool
state. It preserves sibling copies, shared virtual time and recorded history.
Reconnect afterward: the previous world credentials are revoked.

A dataset is not a full snapshot. It does not supply actor permissions, Tool
code, clock values, faults or scheduled work. Firedrill rejects an incompatible
Tool version or unsafe reset instead of falling back to a full reset.
Connections owned by active simulations/tests cannot be manually reset.

## Versions and recovery

```sh theme={null}
firedrill data list --project "$PROJECT_ID"
firedrill data show --project "$PROJECT_ID" --dataset "$DATASET_ID"
firedrill data show --project "$PROJECT_ID" --dataset "$DATASET_ID" \
  --revision 1 --records
```

Record values are hidden from CLI summaries unless you request `--records`.
Revising a dataset creates another immutable version; archiving removes it from
normal selection without rewriting retained source, resets or results.

If a request is interrupted, use the printed `--resume` command. Recovery keeps
the original source, data version, account and request key—even if the dataset
is later revised or archived. Do not create a new key to repeat an uncertain
reset. Resolve its original operation first.

See [starting-data editing](/guides/starting-data),
[reset and time controls](/guides/control-state-time) and
[scenarios](/guides/reusable-scenarios).