You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 814e571
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/concepts/audits.md
+36Lines changed: 36 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -195,6 +195,42 @@ SQLMesh comes with a suite of built-in generic audits that cover a broad set of
195
195
196
196
This section describes the audits, grouped by general purpose.
197
197
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
+
SELECT1AS 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'`:
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
+
198
234
### Generic assertion audit
199
235
200
236
The `forall` audit is the most generic built-in audit, allowing arbitrary boolean SQL expressions.
0 commit comments