The short answer
run_query() (and related patterns) execute SQL during compilation/runtime of dbt and bring results back into Jinja so macros can branch on real warehouse data.
Why people use it
- Look up a max date to parameterize SQL
- Introspect information schema
- Dynamic lists of relations for unions
Risks
- 1Compile-time warehouse hits: every compile/run may fire extra queries (slow CI, extra cost).
- 2Hidden side effects: easy to accidentally run DML if misused.
- 3Non-deterministic compiles: same git SHA can compile differently if data changes mid-flight.
- 4Harder testing: unit-testing Jinja that depends on live tables is painful.
- 5Permission / environment coupling: local compiles need warehouse access for macros that
run_query.
Safer alternatives
- Prefer
is_incremental()+{{ this }}watermarks inside the model SQL - Prefer
graph/builtinsmetadata when you only need project structure - Prefer seeds/vars for static configuration
- Cache results carefully if you must introspect
Interview tip: "run_query is an escape hatch. I treat it as advanced and avoid it for routine incremental watermarks."