# Dataset refresh

URL: /products/data/refresh · Id: `capability:dataset-refresh`

> Dataset refresh re-reads every Source of a Dataset on its schedule or on request, and backfills a past date range.

Dataset refresh re-reads every [Source](/business/nouns/source) of a [Dataset](/business/nouns/dataset) on its schedule or on request, and backfills a past date range.

## Contract
Status `planned`. A Dataset's `refresh` sets how often it re-reads every Source. A refresh reads each Source, records what changed, and sets `refreshedAt`; a backfill reads one Source over a past date range.

| Proposed | Holds |
| --- | --- |
| `Dataset.refresh` | The Dataset and, optionally, one Source; reads it now instead of on schedule |
| `Dataset.backfill` | The Dataset, one Source and a date range; reads every record observed in that range |
| `Dataset.refreshed` | The [Event](/business/nouns/event), with the records added, changed and unchanged per Source |

A refresh never overwrites: each changed value keeps the one it replaced, and a read with `at` returns either.

## Verbs
None.

## Interfaces
None.

## Example
A state publishes a mid-month rate change. Ratebook refreshes that state's Source at once, and every lookup after `refreshedAt` returns the new rate. A lookup with `at` set to the day before returns the old one.