Skip to main content
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:

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:

Rule templates

Templates compile to failing-row SQL on the server. Each has one useful example:
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:
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.