> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambuild.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Audits

> Live and staged data-quality checks using singular and generic SQL 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/`:

```sql theme={null}
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/`:

```sql theme={null}
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`:

```yaml theme={null}
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

```bash theme={null}
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

```bash theme={null}
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.