diff --git a/docs/concepts/audits.md b/docs/concepts/audits.md index 18368cd103..c9fb6a00b2 100644 --- a/docs/concepts/audits.md +++ b/docs/concepts/audits.md @@ -195,6 +195,44 @@ SQLMesh comes with a suite of built-in generic audits that cover a broad set of This section describes the audits, grouped by general purpose. +### Filter rows with condition + +All built-in audits accept an optional `condition` argument to select the rows to audit. Set it on an audit invocation in the model's `audits` property. Omitting it is equivalent to `condition := TRUE`, which keeps the audit's existing row scope. + +Write the condition as a SQL boolean expression in the model's dialect. Use column identifiers and SQL literals normally, without quoting the entire expression as a string. For example, this model checks `customer_id` for `NULL` only in rows where `region = 'us'`: + +```sql linenums="1" +MODEL ( + name demo.orders, + kind FULL, + dialect duckdb, + audits ( + not_null( + columns := (customer_id), + condition := (region = 'us') + ) + ) +); + +SELECT 1 AS customer_id, 'us' AS region; +``` + +For compound predicates, use parentheses to preserve `AND` / `OR` precedence, such as `condition := (region = 'us' AND (customer_id > 0 OR customer_id IS NULL))`. As with SQL `WHERE`, only rows for which the condition evaluates to `TRUE` are included. If a predicate such as `region = 'us'` evaluates to `NULL`, that row is excluded; use `IS NULL` or explicit null handling when those rows should be included. + +Do not use the literal `condition := NULL` to select no rows. Some built-in audits, including `not_null`, combine the condition with other checks using the `@AND` macro, which removes literal `NULL` arguments when rendering SQL. In those audits, a literal `NULL` does not restrict the audited rows. Use `condition := FALSE` to select no rows. + +Aggregate and window-based audits perform their checks over the selected rows. For example, `unique_values` checks duplicates within that population. The following invocation requires at least one row with `region = 'us'`: + +```sql +number_of_rows(threshold := 0, condition := (region = 'us')) +``` + +If no rows match, the result depends on the audit. The filtered `not_null` check above passes, while this `number_of_rows` check fails. + +Each invocation has its own condition and arguments. A condition affects only that audit; it does not filter model materialization, other audits, or downstream models. For incremental by time range models, it further restricts the interval SQLMesh is auditing, without adding historical intervals. + +The `_non_blocking` variants accept the same argument. The condition selects rows, while blocking controls what happens if the audit fails. For a user-defined audit, a parameter named `condition` only filters rows if its query uses the parameter, such as `WHERE @condition`. + ### Generic assertion audit The `forall` audit is the most generic built-in audit, allowing arbitrary boolean SQL expressions.