Audits

An audit passes when its query returns zero rows. Every returned row is a violation.

Singular audit

Concrete audits live recursively under audits/, excluding audits/generic/:

AUDIT (
  name: "no negative totals",
  severity: "warning",
  description: "Line totals should not be negative",
);

SELECT order_id, line_total
FROM __ref("order_items")
WHERE line_total < 0

Header field	Default	Meaning
`name`	none	Required for each block in a multi-audit file
`severity`	`error`	`error` or `warning`
`description`	none	Operator-facing explanation

Audits require at least one model __ref. Source refs are not allowed.

Generic audit

Reusable definitions live under audits/generic/:

AUDIT ();

SELECT @column
FROM __ref("@model")
WHERE @column NOT IN (@'values')

@name inserts a raw identifier, expression, number, string, or list.
@'name' inserts quoted SQL literals.

Instantiate definitions from a pipeline’s schema.yml:

models:
  - name: orders
    columns:
      - name: status
        audits:
          - accepted_values:
              values: [created, paid, shipped, delivered]
              severity: error
    audits:
      - expression_is_true:
          name: totals are non-negative
          expression: "amount_cents >= 0"

Column-level instances receive model and column; model-level instances receive model. Implicit context values cannot be overridden.

Live audits

stb audit
stb audit --select order_items
stb audit --select +daily_revenue
stb audit --select pipeline:order_events

Live audits resolve refs to current direct tables or published virtual-environment views. A failing error-severity audit exits 1; warnings do not. Audit selectors support bare model names, pipeline:<name>, and an optional leading + to include upstream models. A trailing + is not supported for audits.

Staged audits

DEPLOYMENT_ID="replace-with-deployment-id"
stb audit backfill --deployment-id "$DEPLOYMENT_ID"

This virtual-environment command resolves refs to deployment tables, combines data-quality results with replay readiness, and reports ready, caution, or not_ready. audit backfill does not accept --select. Error-severity failures recommend against publishing, but StreamBuild does not enforce that recommendation as a publish lock. Warning-severity failures are included in the results without changing the assessment by themselves. Python macros are available in audit SQL bodies.

Getting Started

Core Concepts

CLI Reference

Examples

Singular audit

Generic audit

Live audits

Staged audits

​Singular audit

​Generic audit

​Live audits

​Staged audits

Singular audit

Generic audit

Live audits

Staged audits