From 814e571092b75307eb76dd40acaffd3a45c9f9fd Mon Sep 17 00:00:00 2001 From: Vamsi-klu Date: Tue, 10 Nov 2026 04:14:44 +0000 Subject: [PATCH 1/2] docs: document condition filters for built-in audits Signed-off-by: Vamsi-klu --- docs/concepts/audits.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/concepts/audits.md b/docs/concepts/audits.md index 18368cd103..58c746037e 100644 --- a/docs/concepts/audits.md +++ b/docs/concepts/audits.md @@ -195,6 +195,42 @@ 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. A `NULL` result excludes the row; use `IS NULL` or explicit null handling when those rows should be included. + +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. From cd3de975f3d32f6cd2669999f7edf42c4cab20e1 Mon Sep 17 00:00:00 2001 From: deepinsight coder <32898216+Vamsi-klu@users.noreply.github.com> Date: Mon, 9 Nov 2026 21:41:45 -0800 Subject: [PATCH 2/2] docs: distinguish literal and evaluated NULL audit conditions Signed-off-by: Codex --- docs/concepts/audits.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/concepts/audits.md b/docs/concepts/audits.md index 58c746037e..c9fb6a00b2 100644 --- a/docs/concepts/audits.md +++ b/docs/concepts/audits.md @@ -217,7 +217,9 @@ MODEL ( 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. A `NULL` result excludes the row; use `IS NULL` or explicit null handling when those rows should be included. +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'`: