Skip to content

Health checks

Verification says the organization stands behind a table’s definition. A health check says its data is still right: it catches the pipeline that stopped delivering rows or the column that is no longer complete, while the table still builds and its definition never moved.

A health check is a named assertion about a table’s contents, such as “orders always have an id” or “this table has rows”, with a plain-language reason attached. Ronja re-checks it every time the table rebuilds, and tells you when the answer changes.

Ronja writes them in Build mode. When she builds a table there, she adds one or two checks in the same turn and says what she is asserting and why.

In a Build-mode chat you can also ask for one: “add a check that orders never has a null id”, or “warn me if this table stops refreshing daily”. She runs it there and then and tells you whether it holds. A check too expensive to evaluate on the table as written is not saved; she tells you, so you can ask for a cheaper one (fewer rows, fewer columns).

Ronja sees a table’s checks in any chat, so you can come back weeks later and ask her to change, add or remove one. She sees every active check and the silenced ones changed most recently, and you can still name any silenced check. She leaves every check you don’t mention as it is.

You can also keep a table’s checks as code, in a pipeline folder beside the table’s SQL, so they live in your version control; or a script can write them over the API. Either way, Ronja runs a new or rewritten check before saving it, and refuses one she can’t evaluate, or one too expensive to evaluate within the time allowed. The API refuses a data check on a table that has never been built; a pipeline folder holds such a check as pending and writes it once the table is published.

Checks are not written on the table page. There you turn a noisy one off.

  • An assertion about the contents: anything true or false about the data, such as a column that is never empty, a count above zero or a value in range. It runs whenever the table rebuilds.
  • A freshness check: “this table should refresh every day.” It catches a table that stops rebuilding altogether, which a check that runs on a rebuild never can. Ronja re-checks it in the background whether or not the table builds, with some slack so an ordinary late run isn’t flagged.

A freshness check also sets the table’s window on the Data map: the Freshness lens judges the table by the check’s interval and turns it red when the check would flag it. A table not built from other tables is judged by its age only when it has a freshness check.

A table never meant to refresh, such as a list of codes or a calendar, can be marked never stale instead: ask Ronja, or set it over the API. The Data map then never calls it stale, and its freshness check is silenced. Only an admin can mark a table whose freshness check is Admin-protected, and a table marked never stale can’t have an active freshness check until it is unmarked.

A table carries up to 20 active content checks and one active freshness check. A freshness check’s interval is 5 minutes to 90 days. Silenced checks don’t count against either limit.

Open a table and go to the Checks tab. Each check shows what it asserts, why it was written, whether it is passing, and what was last observed.

A table with an active check carries a status marker in the feature’s table list and at the top of the table page: Checks passing, Not yet evaluated, Couldn’t be evaluated, or how many checks are failing. A table with no checks, or only silenced ones, has no marker. While something fails, a banner on the table page says how many checks are failing and since when they went from healthy to failing.

In an exploration, a table’s side panel shows the same marker and, when the table has a check, a Checks tab beside Data and Schema, so you can read and silence checks without leaving the conversation.

State What it means
Passing The assertion held the last time it ran.
Failing The assertion did not hold: the data is not what someone said it should be.
Couldn’t be evaluated The check itself broke, usually because a column it names was renamed or dropped. It says nothing about whether your data is right, and isn’t counted as failing.
Not yet evaluated The check hasn’t run yet. It runs at the table’s next rebuild, or the next background re-check for a freshness check.
Silenced Somebody turned it off. It doesn’t run and doesn’t count toward the table’s state.

A check whose rule was saved under Ronja’s older reading of backslashes in SQL can read Couldn’t be evaluated until its rule is edited: see Legacy SQL escapes.

The table stays queryable, its builds keep running, and nothing downstream stops. When Ronja reads from a table whose checks are failing, she says so and names what is failing, so you can judge the number.

A table built from other tables usually has no checks of its own, and its builds succeed while one of its inputs is wrong. So an Admin-protected check that fails also flags every table built from its table, however many steps away, with Input failing. The flag shows on each of those tables’ pages and wherever the table’s health shows; see When something a table is built from is failing.

Only an Admin-protected check does this. A check anyone with edit access can silence stays on its own table, and so does a check that Couldn’t be evaluated: then the checker is broken, not the data. The flag never blocks anything and sends no alert of its own.

A check that starts failing in the background, when the table rebuilds or at a freshness check’s background re-check, raises an alert, at either severity. A check that keeps failing is one alert, not one per run, and the alert ends by itself when the check passes again, is silenced or removed, or its table is archived or moved to the trash.

By default the alert emails the people who maintain the table’s feature and your organization’s Admins (for a table in a private feature, its owner), with an Acknowledge button, and puts one notification in each person’s Notifications bell. For a table in a private feature, the email and the bell name no check or table and give no reason; open the alert in Ronja to see them. While the check stays failing, it is in each morning’s summary instead of a new email. An Admin changes who is told, or switches Table health checks off so that a failing check is recorded on the Alerts tab without email, in Alerts › Settings; see Policies and steps.

The verdict comes from Alert
A table rebuild, or a freshness check’s background re-check Opens when the check fails, ends when it passes
The CLI or the API A check already failing when it is written alerts like a background failure
A chat, when Ronja writes the check, runs it or rewrites what it asserts None: she reports it in the chat. The check’s next background run decides
Renaming a check, rewording its description, or un-silencing it None: these don’t re-run the check

A check that recovers and breaks again within a day reopens the same alert rather than emailing anew. Every alert says since when the check has been failing.

Two related table notices are elsewhere: Table column type changed (When a column changes type) on Notification routing, and the Table updates alert (When a table stops updating).

Turn off a check that is right but that you can’t act on today, so the ones left on still mean something. Who can depends on the check:

  • Anyone with edit access can silence, the default: anyone who can edit the table can add one and switch it off.
  • Admin-protected: only an Admin can create it, silence or un-silence it, downgrade it to the first kind, or remove it. When it fails, the tables built from its table read Input failing (above).
  1. Open the table and go to the Checks tab.
  2. Click Silence on the check.

It stops running and stops counting toward the table’s state. Un-silence brings it back with its history cleared, so a check silenced for a month doesn’t come back reporting a month-long failure. It isn’t re-checked straight away: it reads Not yet evaluated until the table’s next rebuild, or the next background re-check for a freshness check, and alerts if it fails then.

To change what a check asserts instead, ask Ronja in a Build-mode chat: “that check is too strict — allow nulls before 2024”. She rewrites it and runs it again. A check kept in a pipeline folder is changed by editing its file and pushing again.

Remove a check that no longer describes the table, because the column it names is gone for good or its rule stopped applying. Ask Ronja in a Build-mode chat: “remove the check that every order has a region”. She removes only the checks you name. Removing an Admin-protected check needs an Admin.

  • There is no remove button. The Checks tab, the CLI and the API silence a check; only Ronja removes one.
  • A check kept in a pipeline folder comes back at the next push if its checks/ file still declares it, so take it out of the file too (Health checks).
  • To swap a check for another kind, such as a content check for a freshness check, ask Ronja to add the new one first and remove the old one once it is saved.