Skip to content

Commit 814e571

Browse files
committed
docs: document condition filters for built-in audits
Signed-off-by: Vamsi-klu <nrvamsi13@gmail.com>
1 parent 7975a8d commit 814e571

1 file changed

Lines changed: 36 additions & 0 deletions

File tree

‎docs/concepts/audits.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,42 @@ SQLMesh comes with a suite of built-in generic audits that cover a broad set of
195195

196196
This section describes the audits, grouped by general purpose.
197197

198+
### Filter rows with condition
199+
200+
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.
201+
202+
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'`:
203+
204+
```sql linenums="1"
205+
MODEL (
206+
name demo.orders,
207+
kind FULL,
208+
dialect duckdb,
209+
audits (
210+
not_null(
211+
columns := (customer_id),
212+
condition := (region = 'us')
213+
)
214+
)
215+
);
216+
217+
SELECT 1 AS customer_id, 'us' AS region;
218+
```
219+
220+
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.
221+
222+
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'`:
223+
224+
```sql
225+
number_of_rows(threshold := 0, condition := (region = 'us'))
226+
```
227+
228+
If no rows match, the result depends on the audit. The filtered `not_null` check above passes, while this `number_of_rows` check fails.
229+
230+
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.
231+
232+
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`.
233+
198234
### Generic assertion audit
199235

200236
The `forall` audit is the most generic built-in audit, allowing arbitrary boolean SQL expressions.

0 commit comments

Comments
 (0)