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

# Dataset assertions

> Keep visible, durable checks on the data a dataset contains.

A dataset assertion is a read-only rule about the rows in a dataset. Erdo runs the rule and stores its latest result against the data generation it checked. A rule returns failing rows or groups: zero rows means the assertion passes.

## When to add one

Add assertions after you create or configure a feed. They make the feed's important assumptions visible to readers and to the person maintaining its producer. Good first checks cover identity, natural keys, source-meaning ranges, and relationships such as “completed implies completion date.” Keep the description specific: say what must hold and why.

The CLI uses the dataset's slug and the global `--org` flag:

```bash theme={null}
erdo datasets assertions set acme.orders no-duplicate-order \
  --description "Each source order id identifies one order" \
  --unique source_order_id
```

## Reader states

Each active assertion has one reader state:

* `passing`: the latest run found no failing rows.
* `failing`: the latest run found one or more failing rows.
* `could_not_run`: Erdo could not execute the rule; the result includes a bounded reason.
* `stale`: new data arrived after the generation checked by the latest result.
* `unchecked`: the assertion has no result yet, or its definition changed after the latest result.

Use `erdo datasets assertions list` to see the states. Failing assertions appear first, followed by the failing count and description. `run` evaluates synchronously and exits with code 1 when any selected assertion is `failing` or `could_not_run`, which makes it suitable for CI:

```bash theme={null}
erdo datasets assertions list acme.orders
erdo datasets assertions run acme.orders
erdo datasets assertions run acme.orders --slug no-duplicate-order --json
erdo datasets assertions results acme.orders no-duplicate-order
erdo datasets assertions retire acme.orders no-duplicate-order
```

## Rule templates

Templates compile to failing-row SQL on the server. Each has one useful example:

```bash theme={null}
# Identity: every row has a source id
erdo datasets assertions set acme.orders has-source-id \
  --description "Every order must retain its source identifier" \
  --not-null source_order_id

# Natural-key uniqueness: one row per source order
erdo datasets assertions set acme.orders unique-source-order \
  --description "A source order must not appear twice" \
  --unique source_order_id

# Source meaning: only supported order states are accepted
erdo datasets assertions set acme.orders known-state \
  --description "The producer writes only supported order states" \
  --accepted-values status=pending,paid,shipped,cancelled

# Range: a quantity cannot be negative
erdo datasets assertions set acme.orders nonnegative-quantity \
  --description "Order quantities cannot be negative" \
  --range quantity --min 0

# Expression: completed rows must have a completion timestamp
erdo datasets assertions set acme.orders completed-has-date \
  --description "Completed orders need a completion timestamp" \
  --expression "status <> 'completed' OR completed_at IS NOT NULL"
```

Add `--where` to scope a template, for example `--where "status <> 'cancelled'"`. Use `--key-column order_id` to put a stable key first in failure samples.

For a rule that needs SQL, pass a single read-only `SELECT` or `WITH` query. File datasets use the table name `data`:

```bash theme={null}
erdo datasets assertions set acme.filings reviewed-within-a-week \
  --description "A filing is reviewed within 7 days; needs-review is an expected state only while it is new" \
  --sql "SELECT filing_id, review_status, created_at FROM data WHERE review_status IS NULL OR (review_status = 'needs-review' AND created_at < current_date - INTERVAL '7 days')" \
  --key-column filing_id
```

`needs-review` is an expected state, so a new filing in that state passes. The age limit sits in the SQL, so the exception expires on its own and cannot become a permanent exemption without a new version of the assertion.

## How runs are triggered

Erdo runs active assertions after dataset writes and sync completion, and recovery and daily sweeps handle missed or old results. You can also run them manually with the CLI, MCP, or REST. A manual run returns the same summary and assertion results as a list response.

The public REST paths are:

* `GET /v1/datasets/:datasetSlug/assertions`
* `PUT /v1/datasets/:datasetSlug/assertions/:assertionSlug`
* `POST /v1/datasets/:datasetSlug/assertions/run`
* `DELETE /v1/datasets/:datasetSlug/assertions/:assertionSlug`

The corresponding MCP tools are `erdo_list_dataset_assertions`, `erdo_set_dataset_assertion`, `erdo_run_dataset_assertions`, and `erdo_retire_dataset_assertion`.

## What assertions do not catch

Assertions do not catch a value that is plausible and consistent with the rest of the data, or two datasets that share the same upstream defect. They do not prove that a source supplied complete data, that a business decision is correct, or that an external system agrees with the feed.

Rows remain readable when an assertion fails. Fix a wrong row at its producer so the next feed run writes the right value, or use dataset corrections when a correction is the appropriate durable path. Do not loosen an assertion merely to make its state pass.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.