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.
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:--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/assertionsPUT /v1/datasets/:datasetSlug/assertions/:assertionSlugPOST /v1/datasets/:datasetSlug/assertions/runDELETE /v1/datasets/:datasetSlug/assertions/:assertionSlug
erdo_list_dataset_assertions, erdo_set_dataset_assertion, erdo_run_dataset_assertions, and erdo_retire_dataset_assertion.

