Certify a dataset
Take a table from quarantined to certified — declare its contract, add quality checks, submit for review, and sign off.
This guide walks one table from quarantined to certified. You declare what the data
means, add automated quality checks, submit it for review, and a steward signs off. For how
the certification gate decides, see Certification and gates.
For every mb flag, see the CLI reference.
Every table follows one path: quarantined → pending review → certified. A rejection sends it back to quarantined.
Who does what. An editor can write the contract, add checks, run them and submit. Only the table's assigned steward can certify or reject it. A workspace admin assigns the steward, and only an admin can change the per-environment settings described below.
Find the tables waiting for you
Open Data → Quarantine. Its tabs separate the queues: Quarantine Intake, Pending Review and Re-certification. A quarantined table shows as Sandbox on its own page. Quarantine is not an error state: it is where data sits, visible and workable, until it earns the claim.
mb quarantine list # tables that have not earned certification yet
mb status <tableId> # lifecycle state, certification, schema drift, running checks
mb quarantine open <tableId> # write the table's DDL to <tableId>.ddl.sql for editingDeclare the semantic contract
Certification checks the data against what you declare it to be. At minimum, declare:
- Grain — what one row is ("one row per order line"), and its key columns.
- Meaning — what the table as a whole represents.
- Steward — the one person who certifies it. A workspace admin assigns the steward. A table with no steward can't be certified until one is assigned.
In the dashboard, open the table's Governance Review page and fill in Grain (row-level meaning), Grain type with its key columns, and Meaning summary (table-level). A workspace admin picks the Steward (approver) on the same page.
With mb, contract set-intent writes grain, meaning and the structured grain declaration in one
call. On a table with no contract yet, --grain and --meaning are required:
mb contract set-intent <tableId> \
--grain "One row per order line" \
--meaning "Every order line booked, net of cancellations" \
--grain-type ONE_PER_ENTITY --grain-key order_id,line_no \
--intent DECISION --allowed-consumers HUMAN,AIGrain types: ONE_PER_ENTITY, AGGREGATE, SNAPSHOT, EVENT_STREAM, UNKEYED_APPEND. A grain
that can't be expressed as columns takes --grain-not-expressible and is recorded as not verified.
Add automated quality checks
Every table gets a standard suite of checks, including null rates, grain uniqueness and required columns. You add your own on top, as a YAML file you can review, diff and ship from CI.
patternChecks:
- name: email_format
column: email
regex: "^[^@]+@[^@]+$"
severity: SOFT_FAIL
customPredicates:
- name: amount_non_negative
sql: "amount >= 0"
severity: HARD_FAIL
scope: per_row # optional: also check each row as it is written
crossColumnChecks:
- name: ship_after_order
expression: "shipped_at >= ordered_at"
severity: HARD_FAIL
fieldOverrides:
- field: middle_name
nullRate: { warn: 0.6, fail: 0.9 }HARD_FAIL checks block by default. SOFT_FAIL checks are reported but do not block by default.
Applying a file replaces the pattern, custom and cross-column lists wholesale. A null-rate override
replaces only the fields it names. Any other top-level key is rejected.
mb gate get <tableId> -o checks.yml # fetch the current checks
mb gate validate -f checks.yml # offline check, no server call
mb gate diff <tableId> -f checks.yml # exit 0 if identical, 1 if different
mb gate apply <tableId> -f checks.yml # save to the table's contractThe same editor is on the table's Settings → Gates tab (Apply saves). Applying notifies no one. On a certified table, applying new checks sends it back for recertification.
Start from suggested checks
Möbius can propose a starting set of checks from the data's own shape. Each proposal carries the evidence behind it. Column names are treated as hints only, never as evidence.
mb gate suggest <tableId> > proposed.yml # justification for each proposal prints to stderr
mb gate suggest <tableId> | mb gate apply <tableId> -f -Before applying, review each proposal and fill in any TODO SQL. On Settings → Gates,
AI-suggest opens the Möbius Agent, the in-app assistant, with the same request. That button works for held tables
only. For an in-place table, use mb gate suggest, which works once the table has a captured
profile.
Run the checks and read the verdict
A dry run evaluates every check and returns the result. It changes nothing.
mb gate run <tableId> --wait # full scan, block until done
mb gate run <tableId> --sample random:1000 # sample instead: head:N, tail:N, random:N, chunks:K@N
mb gate result <jobId> # read a finished run's result
mb status <tableId> --watch # follow running checks until none remainOn Settings → Gates, use Run dry-run. A sampled run is labelled as a sample. On an
in-place table, head, tail and chunks sampling need a declared grain.
Submit for review
When the checks look right, run mb gate submit <tableId> --wait, or click Submit for review
on Settings → Gates. A submission always scans every row. If the table's recent baseline is
still fresh, only your added checks are re-run, and the result says so.
You can submit from quarantined or baseline-verified. If the checks pass under the environment's enforcement posture (below), the table moves to pending review and the steward is notified. If a blocking check fails, the table stays where it is: fix the data or the checks, then submit again.
Choose the enforcement posture
Each environment has its own enforcement posture, the Gate mode setting. An admin sets it on Workspace → Environments, in that environment's section. For a failed check, it decides:
| Gate mode | A failed check at submission | A row that fails a per-row check on write |
|---|---|---|
| Enforcing | HARD_FAIL stops the submission (by default) | The row is quarantined and not written |
| Advisory | Recorded, and the submission proceeds | Recorded, and the row still lands |
| Off | Not enforced | Checks do not gate writes |
Advisory lets you introduce checks to a live estate without stopping it, then switch to Enforcing.
Review the meaning, and run the statistical battery
When a steward certifies, two checks run beyond the automated quality checks:
- Meaning review asks whether the data is coherent with what its contract claims. It produces a rating from green to black. It can never override a failed hard check.
- Statistical battery compares the table's distributions against its last certified snapshot. Its findings are attached to the certification report as evidence. It never blocks certification and never changes the rating.
Which of these run is a per-environment setting, Gate selection, on Workspace → Environments:
- Automated quality checks only. The report says that the meaning review was skipped.
- Quality checks plus meaning review (the default).
- Quality checks, meaning review and the statistical battery.
You can also run either one on its own. A standalone run is evidence only and certifies nothing:
mb gate run <tableId> --gate 2 # meaning review
mb gate run <tableId> --gate 3 --baseline <reportId> # statistical battery vs a named report
mb gate status <jobId> --gate 2Sign off
The steward opens Governance Review for the table (from the Pending Review queue) and clicks Certify or Reject to Intake. From the terminal:
mb certify <tableId> --note "Reviewed with finance" --evidence signoff.pdf
mb reject <tableId> --reason "Grain is wrong: duplicates per order_id"--evidence (which requires --note) sends only the file's name, size and SHA-256 hash; the file
stays on your machine. mb certify exits 1 on failure, printing the rating and each failed
check. If the data moved since submission it refuses with STALE_PROOF: submit again. A rejection
returns the table to quarantine and notifies the person who submitted it.
Who may sign
Only the table's assigned steward can certify or reject it, and they need the Steward role or above and read access to the table. No one else can sign in their place, including admins and the table's owner. If the table has no steward, certifying is refused until a workspace admin assigns one; an admin can also reassign the steward.
Whether the steward may approve their own work is a per-environment setting, Certification approval policy, on Workspace → Environments:
| Setting | When the assigned steward may certify |
|---|---|
| Self-certification allowed (default) | Always, even if they submitted it or own the table |
| Steward approval required | Only if someone else submitted it |
| Separate steward (four-eyes) | Only if someone else submitted it and they don't own the table |
A change applies to later certifications only; certified tables are not re-evaluated.
Read the certification report
Every certification attempt produces an immutable report. The table's Certification Report
page lists every check, what it measured, and the exact SQL it ran, so you can re-run it yourself. The Workspace API serves the same
report at GET /api/tables/{id}/certification-report/latest. You can open a report whether or not
the table is certified.
When certification fails, ask the Möbius Agent (or your AI tool over the Workspace MCP) why did this table fail certification? The agent explains each failed check in plain language and suggests a next step. It works from the report's check outcomes, never from row values.
mb versions list <tableId> shows the certification history: version, when, by whom, and the
grain at the time.
Recertification
A certification is a claim about the data as it was when checked. A certified table re-enters review when something material changes, for example:
- Schema drift. The table's actual shape no longer matches the shape it was certified against.
- New checks applied to a certified table.
- A pipeline signal from the Workspace API. Your pipeline's post-run step calls
POST /api/workspace/recertifywith the tables it rewrote, or with dbt'srun_results.json. This files a recertification request for each certified table it names. For a lighter signal that re-checks only newly loaded rows and probes for drift, callPOST /api/workspace/data-loadedwith a token that carries theworkspace:write:regatescope. Both apply to in-place tables.
Open requests appear in the Re-certification queue on Data → Quarantine. There, the table's steward sees what changed since the last certification before approving, and can approve several requests at once. From the terminal:
mb recertification list --table <tableId> --status PENDING,IN_REVIEW
mb recertification dismiss <requestId> --notes "Cosmetic rename, no change in meaning"Dismissing a request acknowledges it and leaves the certification unchanged.
Some connectors accept purely additive changes, such as a new column on a schemaless source, without a review. The change is recorded, and the new column is not added to the certified view until the steward reviews it.