Skip to main content
Checks arrive from many tools, each with its own naming. A dbt not_null test, a dbt not_null_proportion test, an elementary test, a SQLMesh audit, and a hand-written SQL assertion can all be checking the same thing — that a column has no missing values — yet none of them share a name. Left as-is, there’s no way to ask “how well is completeness covered across my stack?” without knowing every tool’s vocabulary. Check categorisation solves this. Coalesce Quality categorises every check (dbt tests, SQLMesh audits, custom assertions, …) as it is ingested, mapping each one onto a consistent taxonomy regardless of which tool produced it. That shared vocabulary is what powers the analytics dashboards, coverage reports, and filtering across the product — so a check only shows up in the right place if it is categorised correctly. Categorisation happens along two independent dimensions: The governance dimension maps onto the data quality dimensions you see in Analytics. The technical dimension groups checks by their validation logic — for example every not_null variant across dbt, SQLMesh and custom SQL collapses into a single nullness group. A check carries one category per dimension. The two are resolved independently, so a single check can be Completeness for governance and nullness for technical at the same time.

​
Where categories come from

For each dimension, a check’s effective category is resolved from three sources, in descending priority:
  1. Admin override — a per-check category set by a workspace admin from the Checks tab (see Per-check overrides). Overrides always win.
  2. Producer-explicit category — set directly by the producer, or carried on the source asset as a quality.check_category / quality.governance_category annotation.
  3. Computed category — derived by the categorisation engine from the categorisation rules described below. A matching workspace rule wins over a matching global rule.
If none of these produces a value the check is Uncategorised for that dimension. When a higher tier supplies the value, the UI still shows which rule would have matched — so you can see what an override or explicit value is masking.
quality.check_category and quality.governance_category are the documented annotation names. The original synq.check_category and synq.governance_category names remain supported permanently, so existing configurations do not need to change.Both namespaces also accept an underscore in place of the dot (for example, quality_check_category). A producer may prefix the annotation name; matching by suffix means a name such as dbt.tag.quality.check_category resolves the same way. Use the quality.* names in new configurations.

​
Categorisation rules

A categorisation rule says “checks matching this predicate get this category”. Rules are managed under Health → Check categorisation, which has a section per dimension (Governance, Technical) plus a Checks section for inspecting how individual checks were categorised. Each rule has:
  • a category — the value assigned to checks it matches (free-form, e.g. completeness or nullness);
  • a priority — when several rules in the same scope match the same check, the highest-priority rule wins;
  • a predicate — either a structured predicate or a CEL expression, never both.
Rules created in the app are workspace rules — they apply only to your workspace and take precedence over the global, Coalesce Quality-provided rules whatever their priority. A global rule applies only when no workspace rule matches the check, so overriding a global rule takes a workspace rule that matches, not a higher priority number. Global rules are maintained by Coalesce Quality administrators.

​
Structured predicate

The structured predicate matches on the facts a check already carries. A check matches when every non-empty group below contains the check’s value — an empty group matches anything. For example, a rule with Platforms = dbt and Kinds = not_null, not_null_proportion matches every dbt not-null-style test and nothing else. Names use * as a wildcard for any sequence of characters (every other character is literal); multiple patterns are OR-ed. Annotation predicates match a check’s annotations by key, with one of four modes per key: The platform and asset-type dropdowns are populated from checks actually present in your workspace and narrow as you pick, so you only ever see real values.

​
CEL expressions

When the structured predicate isn’t expressive enough — string prefixes, regular expressions, combining conditions with || — switch the predicate to a CEL expression. The rule matches a check when the expression evaluates to true. CEL (Common Expression Language) is a small, safe expression language. The following variables are available: PLATFORM_* and ASSET_TYPE_* enum names are exposed as string constants, so you can compare against them directly.
Prefer the structured predicate when it can express your rule — it’s easier to read at a glance and cheaper to evaluate. Reach for CEL only for the cases it can’t cover.

​
Live impact preview

While you edit a rule, the dialog runs a live impact preview against the checks in your workspace, showing how many checks the rule would match before you save. A rule with no predicate (an empty structured predicate and no CEL expression) is flagged as a catch-all — it would match every check at its priority — and the preview is skipped until you add at least one condition.

​
Per-check overrides

The Checks section lists every check with its resolved Technical and Governance categories and the source that produced each one. Workspace admins can pin a category on an individual check with Set explicit category, which sets a Technical and/or Governance value that takes precedence over both the producer-explicit value and any rule match. Clearing both dimensions removes the override, and the check falls back to its underlying category. You can also create a rule straight from a check — the rule dialog opens prefilled with that check’s platform, asset type, package, and kind so it matches checks shaped like it.

​
Recategorisation

Whenever you add, edit, or delete a rule, Coalesce Quality enqueues a recategorisation sweep that re-evaluates existing checks against the updated rule set. The Check categorisation page shows the sweep’s progress; new checks are categorised as they are ingested.

​
Managing categorisation programmatically

The Check categorisation screens are one client of the categorisation API. The same rules and per-check overrides are available over the public API and to an AI assistant over MCP, and all three drive the same services — so a rule authored by an assistant is the same rule the page shows, subject to the same precedence and the same recategorisation sweep.
  • Public API — synq.entities.checks.v2.ChecksCategorisationRulesService covers the rules (list them, preview a candidate’s reach, upsert, delete, and read the recategorisation status); synq.entities.checks.v2.ChecksCategoriesService covers per-check overrides, the workspace’s category vocabulary, and the attribute values a predicate can be built from. Reading needs a token with SCOPE_POLICIES_READ, writing needs SCOPE_POLICIES_EDIT. See the API reference and API scopes.
  • MCP — the check categorisation tools let an AI assistant review what is uncategorised, draft a rule, preview its impact, and save it once you approve. Reading is covered by read-only consent; saving or deleting a rule and setting a per-check override need the Governance permission, and every write is confirmation-gated.