Möbius
Guides

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 editing

Declare 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,AI

Grain 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 contract

The 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 remain

On 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 modeA failed check at submissionA row that fails a per-row check on write
EnforcingHARD_FAIL stops the submission (by default)The row is quarantined and not written
AdvisoryRecorded, and the submission proceedsRecorded, and the row still lands
OffNot enforcedChecks 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:

  1. Automated quality checks only. The report says that the meaning review was skipped.
  2. Quality checks plus meaning review (the default).
  3. 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 2

Sign 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:

SettingWhen the assigned steward may certify
Self-certification allowed (default)Always, even if they submitted it or own the table
Steward approval requiredOnly 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/recertify with the tables it rewrote, or with dbt's run_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, call POST /api/workspace/data-loaded with a token that carries the workspace:write:regate scope. 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.

On this page