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
1. Compile-time warehouse hits: every compile/run may fire extra queries (slow CI, extra cost). 2. Hidden side effects: easy to accidentally run DML if misused. 3. Non-deterministic compiles: same git SHA can compile differently if data changes mid-flight. 4. Harder testing: unit-testing Jinja that depends on live tables is painful. 5. Permission / 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."