Skip to content

Commit ce1935f

Browse files
committed
feat(cli): render attached and standalone audit SQL
Signed-off-by: Vamsi-klu <nrvamsi13@gmail.com>
1 parent 7975a8d commit ce1935f

6 files changed

Lines changed: 803 additions & 10 deletions

File tree

‎docs/concepts/audits.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,36 @@ Standalone audits can declare dependencies using the `depends_on` property. SQLM
190190
!!! note
191191

192192
Standalone audits are non-blocking only. Because they are not associated with a single model, SQLMesh cannot determine which model should be blocked if the audit fails.
193+
194+
## Render audit SQL
195+
196+
Use [`sqlmesh render --audit`](../reference/cli.md#render) to inspect an audit's rendered failure query. Pass the audit's metadata `name`, rather than its SQL filename.
197+
198+
For an audit attached to a model, supply the model name. SQLMesh uses the audit definition and arguments configured on that model, including built-in, user-defined, and inline audits. For the parameterized example above:
199+
200+
```bash
201+
sqlmesh render sushi.items --audit does_not_exceed_threshold \
202+
--start 2024-01-01 --end 2024-01-31 --execution-time 2024-02-01
203+
```
204+
205+
This renders both invocations in their configured order, keeping their distinct `column` and `threshold` arguments. Each statement has a SQL comment identifying the audit and invocation number, and ends with a semicolon. Blank lines separate the statements. The audit must be attached to the supplied model; SQLMesh does not infer arguments for an unattached audit.
206+
207+
For a standalone audit, omit the model name. For the standalone example above, use `--no-format` to write plain SQL to a file:
208+
209+
```bash
210+
sqlmesh render --audit assert_item_price_is_not_null \
211+
--start 2024-01-01 --end 2024-01-31 --execution-time 2024-02-01 \
212+
--no-format > audit.sql
213+
```
214+
215+
Without a model name, SQLMesh resolves only standalone audits. If an attached and a standalone audit share a name, supplying the model selects the attached audit; omitting the model selects the standalone audit. Explicitly requested audits render even if they have `skip TRUE`, so you can inspect queries that normal execution would skip.
216+
217+
The output uses the audit's declared dialect, falling back to the attached model's dialect or the owning project's dialect. Pass `--dialect` to choose a different output dialect. The audit's input dialect still controls how SQLMesh parses its definition. Formatting options such as `--indent` override the owning project's formatting defaults.
218+
219+
Audit rendering does not support `--expand`. It uses the audit's normal table references and interval filters. Model rendering without `--audit` keeps its existing behavior and requires a model name.
220+
221+
The command does not execute the audit's failure query. Project loading can read state, rendering can inspect column metadata, and user-defined macros can execute database queries as usual.
222+
193223
## Built-in audits
194224
SQLMesh comes with a suite of built-in generic audits that cover a broad set of common use cases. Built-in audits are blocking by default, but they all have non-blocking counterparts which you can use by appending `_non_blocking` - see [Non-blocking audits](#non-blocking-audits).
195225

‎docs/reference/cli.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -432,11 +432,15 @@ Options:
432432
## render
433433

434434
```
435-
Usage: sqlmesh render [OPTIONS] MODEL
435+
Usage: sqlmesh render [OPTIONS] [MODEL]
436436
437-
Render a model's query, optionally expanding referenced models.
437+
Render a model's query, optionally expanding referenced models, or render
438+
audit queries.
438439
439440
Options:
441+
--audit TEXT Render all invocations of this audit on MODEL,
442+
or a standalone audit without MODEL. Cannot be
443+
used with --expand.
440444
-s, --start TEXT The start datetime of the interval for which
441445
this command will be applied.
442446
-e, --end TEXT The end datetime of the interval for which this
@@ -464,6 +468,8 @@ Options:
464468
--help Show this message and exit.
465469
```
466470

471+
`MODEL` is required when rendering a model or an attached audit. Omit it only when rendering a standalone audit with `--audit`. Use the audit's metadata name, rather than its filename. See [Render audit SQL](../concepts/audits.md#render-audit-sql) for examples, repeated invocations, output dialect selection, and rendering behavior.
472+
467473
## rewrite
468474

469475
```

‎sqlmesh/cli/main.py‎

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@
44
import os
55
import sys
66
import typing as t
7+
from contextlib import redirect_stdout
78
from pathlib import Path
89

910
import click
11+
from sqlglot.errors import SqlglotError
1012

1113
from sqlmesh import configure_logging, remove_excess_logs
1214
from sqlmesh.cli import error_handler
@@ -169,7 +171,11 @@ def cli(
169171
logger.exception("Failed to initialize SQLMesh context")
170172
raise
171173

172-
if load and not context.models:
174+
if (
175+
load
176+
and not context.models
177+
and not (ctx.invoked_subcommand == "render" and context.standalone_audits)
178+
):
173179
raise click.ClickException(
174180
f"`{paths}` doesn't seem to have any models... cd into the proper directory or specify the path(s) with -p."
175181
)
@@ -279,7 +285,11 @@ def init(
279285

280286

281287
@cli.command("render")
282-
@click.argument("model")
288+
@click.argument("model", required=False)
289+
@click.option(
290+
"--audit",
291+
help="Render all invocations of this audit on MODEL, or a standalone audit without MODEL. Cannot be used with --expand.",
292+
)
283293
@opt.start_time
284294
@opt.end_time
285295
@opt.execution_time
@@ -296,16 +306,62 @@ def init(
296306
@cli_analytics
297307
def render(
298308
ctx: click.Context,
299-
model: str,
309+
model: t.Optional[str],
300310
start: TimeLike,
301311
end: TimeLike,
302312
execution_time: t.Optional[TimeLike] = None,
303313
expand: t.Optional[t.Union[bool, t.Iterable[str]]] = None,
304314
dialect: t.Optional[str] = None,
305315
no_format: bool = False,
316+
audit: t.Optional[str] = None,
306317
**format_kwargs: t.Any,
307318
) -> None:
308-
"""Render a model's query, optionally expanding referenced models."""
319+
"""Render a model's query, optionally expanding referenced models, or render audit queries."""
320+
if audit is not None:
321+
if expand:
322+
raise click.UsageError("--audit cannot be used with --expand.", ctx)
323+
try:
324+
with redirect_stdout(sys.stderr):
325+
queries = ctx.obj.render_audit(
326+
model,
327+
audit_name=audit,
328+
start=start,
329+
end=end,
330+
execution_time=execution_time,
331+
)
332+
owner = (
333+
ctx.obj.get_model(model, raise_if_missing=True)
334+
if model is not None
335+
else ctx.obj.standalone_audits[audit.lower()]
336+
)
337+
definition = next(a for a, _ in owner.audits_with_args if a.name == audit.lower())
338+
config = ctx.obj.config_for_node(owner)
339+
options = {
340+
**config.format.generator_options,
341+
**{k: v for k, v in format_kwargs.items() if v is not None},
342+
}
343+
output_dialect = (
344+
dialect
345+
if dialect is not None
346+
else definition.dialect or owner.dialect or config.dialect
347+
)
348+
label = " ".join(definition.name.splitlines())
349+
statements = [
350+
f"-- Audit: {label}, invocation {index}\n{query.sql(pretty=True, dialect=output_dialect, **options)};"
351+
for index, query in enumerate(queries, 1)
352+
]
353+
except (SQLMeshError, SqlglotError, ValueError) as ex:
354+
# Click reports these errors on stderr, preserving redirectable SQL on stdout.
355+
raise click.ClickException(str(ex)) from ex
356+
sql = "\n\n".join(statements)
357+
if no_format:
358+
print(sql)
359+
else:
360+
ctx.obj.console.show_sql(sql)
361+
return
362+
363+
if model is None:
364+
raise click.MissingParameter(param_hint="'MODEL'", param_type="argument", ctx=ctx)
309365
model = ctx.obj.get_model(model, raise_if_missing=True)
310366

311367
rendered = ctx.obj.render(

‎sqlmesh/core/context.py‎

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080
from sqlmesh.core.loader import Loader
8181
from sqlmesh.core.linter.definition import AnnotatedRuleViolation, Linter
8282
from sqlmesh.core.linter.rules import BUILTIN_RULES
83-
from sqlmesh.core.macros import ExecutableOrMacro, macro
83+
from sqlmesh.core.macros import ExecutableOrMacro, RuntimeStage, macro
8484
from sqlmesh.core.metric import Metric, rewrite
8585
from sqlmesh.core.model import Model, update_model_schemas
8686
from sqlmesh.core.config.model import ModelDefaultsConfig
@@ -1286,6 +1286,87 @@ def render(
12861286
**kwargs,
12871287
)
12881288

1289+
@python_api_analytics
1290+
def render_audit(
1291+
self,
1292+
model_or_snapshot: t.Optional[ModelOrSnapshot] = None,
1293+
*,
1294+
audit_name: str,
1295+
start: t.Optional[TimeLike] = None,
1296+
end: t.Optional[TimeLike] = None,
1297+
execution_time: t.Optional[TimeLike] = None,
1298+
) -> t.List[exp.Query]:
1299+
"""Render an audit's failure queries without running them.
1300+
1301+
Args:
1302+
model_or_snapshot: The audited model, name, or snapshot. Omit for a standalone audit.
1303+
audit_name: The audit metadata name. All effective invocations on the model are rendered.
1304+
start: The start of the interval to render.
1305+
end: The end of the interval to render.
1306+
execution_time: The execution time reference, defaulting to now for the entire call.
1307+
1308+
Returns:
1309+
Failure queries in invocation order, including explicitly requested skipped audits.
1310+
1311+
Rendering can read column metadata, and user macros retain their normal execution behavior.
1312+
"""
1313+
audit_name = audit_name.lower()
1314+
model = (
1315+
self.get_model(model_or_snapshot, raise_if_missing=True)
1316+
if model_or_snapshot is not None
1317+
else None
1318+
)
1319+
if model is not None:
1320+
audits = [
1321+
(audit, args) for audit, args in model.audits_with_args if audit.name == audit_name
1322+
]
1323+
if not audits:
1324+
raise SQLMeshError(f"Audit '{audit_name}' is not attached to model '{model.name}'.")
1325+
else:
1326+
standalone_audit = self.standalone_audits.get(audit_name)
1327+
if standalone_audit is None:
1328+
from sqlmesh.core.audit.builtin import BUILT_IN_AUDITS
1329+
1330+
if audit_name in BUILT_IN_AUDITS or any(
1331+
audit.name == audit_name
1332+
for model in self.models.values()
1333+
for audit, _ in model.audits_with_args
1334+
):
1335+
raise SQLMeshError(f"Audit '{audit_name}' requires a model. Supply MODEL.")
1336+
raise SQLMeshError(
1337+
f"Cannot find standalone audit '{audit_name}'. Model-attached audits require MODEL."
1338+
)
1339+
audits = [(standalone_audit, {})]
1340+
1341+
snapshots = self.snapshots
1342+
deployability_index = DeployabilityIndex.create(snapshots.values(), start=start)
1343+
execution_time = now() if execution_time is None else execution_time
1344+
adapter = self._get_engine_adapter(model.gateway if model is not None else None)
1345+
queries = []
1346+
for audit, audit_args in audits:
1347+
audit_args = audit_args.copy()
1348+
audit_args.pop("blocking", None)
1349+
kwargs: t.Dict[str, t.Any] = {
1350+
"start": start,
1351+
"end": end,
1352+
"execution_time": execution_time,
1353+
"snapshots": snapshots,
1354+
"deployability_index": deployability_index,
1355+
"engine_adapter": adapter,
1356+
"runtime_stage": RuntimeStage.AUDITING,
1357+
**audit_args,
1358+
}
1359+
if model is not None:
1360+
snapshot = snapshots.get(model.fqn)
1361+
# Before the first plan there is no physical table to map to, as in model rendering.
1362+
if snapshot is not None and snapshot.version is None:
1363+
kwargs.setdefault("this_model", model.fqn)
1364+
query = model.render_audit_query(audit, **kwargs)
1365+
else:
1366+
query = t.cast(StandaloneAudit, audit).render_audit_query(**kwargs)
1367+
queries.append(query)
1368+
return queries
1369+
12891370
@python_api_analytics
12901371
def evaluate(
12911372
self,

0 commit comments

Comments
 (0)