How Integrity Checks Work¶

Integrity checks are the primary operational signal that a Numera data load has completed correctly. This page explains what they are, when they run, and why some checks behave differently from others.

What an integrity check is¶

A Numera integrity check is a dbt singular test: a SQL query that returns rows only when an invariant has been violated. If the query returns zero rows, the check passes; if it returns one or more rows, the check fails and those rows are reported as the failure evidence.

This is different from schema tests (such as not_null or unique), which are automatically generated from column declarations and test structural properties of individual columns. Singular tests express business-level or pipeline-level invariants that cannot be captured by column-level declarations alone — for example, "the row count of this fact table must equal the row count of its source joined through a specific chain."

All integrity checks in Numera follow the check_ prefix convention. Checks in numera-core/tests/ are part of the shared core package; checks in dbt/tests/ are EWE-specific.

When checks run¶

Integrity checks run automatically after every scheduled dbt load. Results are surfaced via fct_integrity_check, which queries Snowflake's INFORMATION_SCHEMA audit tables to aggregate pass/fail status, check name, and error row count per load.

After each load, review fct_integrity_check for any checks where num_errors > 0. An Error-severity failure means the load has been flagged as failed and warrants investigation before relying on the data. A Warning-severity check will have num_errors > 0 but the load will still have completed.

Severity levels¶

Each check has a severity level, which determines whether a failure blocks the load or is advisory.

Severity	Meaning
Error	Load is flagged as failed. The data may be incomplete or incorrect. Investigation is required before the next load cycle.
Warning	Load continues. The check is an advisory signal; failures are expected to remain small and self-resolving in normal operation.

The vast majority of checks run at Error severity. Three checks can emit Warning-level signals — two of them are Warning-only, and one is dual-severity:

check_bav_dim_tran_info_coverage_scd_endur_deal_enhanced (Warning only) — warns if BAV (bav_dim_tran_info_key) coverage is worse than exact-version coverage in scd_endur_deal_enhanced. In normal operation this should never fail, but it is advisory because some deals legitimately have no tran_info.
check_cardinality_dim_tran_info (Warning only) — warns if dim_tran_info exceeds 15,000,000 rows. High cardinality in this dimension degrades query performance; the check is a warning rather than an error because the model continues to function.
check_fct_pnl_deal_vs_pnl_detail (Warning + Error) — warns if any deal-level PnL discrepancy between fct_pnl_deal and sat_endur_sim_result_pnl_detail exceeds 0 rows, and escalates to Error if it exceeds 5,000 rows (which does flag the load as failed). Small discrepancies are expected during the settling period immediately after a sim run; large discrepancies indicate a structural problem.

Timing and grace windows¶

Many checks include a lookback window and a grace period. These are deliberate design choices to avoid false positives from data that has not yet had time to arrive.

Lookback window: Most checks examine only recent data — typically the last 7 days. This bounds the scope of the check to activity that should be fully resolved by now, avoiding spurious failures from very old data that may have legitimate historical gaps.

Grace period: Several checks exclude the most recent 1–2 days. For example, check_dim_tran_info_is_missing checks only deals that are 2–7 days old: brand-new deals (< 2 days) may still be awaiting their tran_info batch from the Endur exporter, and flagging them would produce transient false positives that self-resolve on the next load.

What this means in practice: A check that fires immediately after a system upgrade, a source outage, or a maintenance window may be a timing artefact. The lookback window means the check will continue to fire on subsequent loads until the gap is more than the window's width old. If a check fires and then clears on the next load without any intervention, it was most likely a transient timing issue.

Disabled tests¶

Eleven checks are currently disabled (enabled = false in their dbt configuration). Disabled checks have been superseded by improved versions, are pending a fix to their underlying logic, or relate to pipeline features not yet deployed to all stacks. They do not run as part of the normal load cycle and are excluded from this catalogue.

Surfacing failures¶

After every load, query fct_integrity_check in Snowflake to see which checks fired:

SELECT
    check_name,
    num_errors,
    load_id,
    loaded_at
FROM fct_integrity_check
WHERE num_errors > 0
ORDER BY loaded_at DESC;

The check_name field matches the names in the Check Catalogue. Use the catalogue to look up the invariant being tested, its severity, and suggested investigation steps.