# dbt macros and ref() explained in VS Code > Hover over a dbt macro or ref() in VS Code. See which models use the macro and how deep the model sits, then ask Altimate Code to explain it. Source: https://altimate.ai/product-highlights/dbt-macros-and-ref-explained-on-hover [.md](https://altimate.ai/product-highlights/dbt-macros-and-ref-explained-on-hover.md) Copy as MD PowerUser Plugin for dbt ## Hover Over a dbt Model Reference or Macro to See Its Depth and Who Uses It Hover over a dbt macro or ref() in VS Code. See which models use the macro and how deep the model sits, then ask Altimate Code to explain it. Atharva ShahOct 16, 20263 min read Hover over a dbt model reference or macro to see its depth and who uses it TL;DR - **What it is.** Hover cards on every `ref()` and macro call in a dbt model, from the PowerUser Plugin for dbt. Each card carries an Altimate Code action, which needs a free Altimate API key. - **Who it is for.** Analytics engineers who join a team, inherit a long dbt model or review a pull request full of Jinja. - **What you get.** The depth and columns behind each `ref()`, the models that use each macro, and an explanation one click away. Long dbt models mix SQL with `ref()` calls and macros. The compiled SQL shows the result of the Jinja, but it hides where each piece came from. Before you change either one, you need two answers. What does the referenced model contain, and what does the macro do? Hover cards answer both inside the file you are reading. ## Hover Over a Model Reference to See Depth and Columns Hover over any `ref()` and a card appears. On `ref('stg_orders')` it reads DAG Depth 1, which means the longest path from a source to that model is one node. So `stg_orders` is a staging model that reads straight from a source. The card also lists the columns this model pulls from it, here `order_id` and `status`. Use the depth to judge how far a change travels. A staging model at depth 1 feeds every model built on top of it. A high depth means many layers sit underneath. A wrong number there may start far upstream. The hover card on ref('stg\_orders') at line 11 of orders.sql. It reads DAG Depth 1, The longest path of models between a source and this model is 1 nodes long, then lists the ref stg\_orders, the columns order\_id and status, and an Explain transformation action. Click **Explain transformation** on the card. Altimate Code walks through what the referenced model selects, filters, joins and aggregates, step by step. ## Hover Over a Macro to See Which Models Use It Hover over a macro call and the card names the macro and the models that reference it. In the demo, `pct_of_total` is used only by `orders`. Two actions sit on the card: **Explain what this macro does** and **Find risky usages**. The second action checks every call for: - Missing arguments. - Wrong argument types. - Edge cases the macro does not handle. - Anti-patterns in how the macro is called. Run it before you change a macro that several models share. A macro used by one model is cheap to change. A macro used by twenty models needs a plan. The hover card on the pct\_of\_total macro call at line 55. It reads (Macro) pct\_of\_total, (Referenced by) orders, and offers Explain what this macro does and Find risky usages. Spotlight 5 video, dbt ref() and macros explained on hover ## Go From the Whole Model Down to One Dependency Each action opens its own Altimate Code session, so one chat explains the model and another explains a macro. Altimate Code asks before it runs a shell command, such as a search for every file that calls the macro. You approve it once, always or not at all. Start with the whole model, then open a second session for the one macro you do not trust. Two Altimate Code chat tabs, Explain: stg\_orders and Explain macro: pct\_of\_total, with a Permission required card for a bash command that searches SQL files for pct\_of\_total, offering Allow once, Allow always and Reject. The [hover actions guide](https://help.altimate.ai/dbt-power-user/develop/autocomplete/#hover-actions) lists every action on each card. ### Install the dbt VS Code extension [Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=innoverio.vscode-dbt-power-user) [Book a 30-min demo →](https://calendly.com/d/ctnv-rbc-yr3/altimate-ai-overview) [Read the docs →](https://help.altimate.ai/dbt-power-user/) ## Frequently Asked Questions What does DAG Depth mean on a ref() hover card? It is the longest path of models between a source and the model you referenced. A depth of 1 means one hop from a source, which usually marks a staging model. A higher number tells you how many layers of models sit underneath. Which hover actions does a macro get? Two actions. Explain what this macro does covers its purpose, parameters and usage. Find risky usages checks every call to the macro for missing arguments, wrong types, edge cases and anti-patterns. Do I still need the compiled SQL? Yes, for the full query the warehouse runs. The PowerUser Plugin for dbt shows it with one click, as the [compiled SQL guide](https://help.altimate.ai/dbt-power-user/develop/compiledCode/) explains. Hover cards answer a narrower question about one ref() or one macro, without reading the whole compiled file. Does the hover card need an API key? The Altimate Code actions on the card need a free Altimate API key and the Datamates extension, which installs with the PowerUser Plugin for dbt. The chat runs on your own model provider key or on the Altimate LLM Gateway. Can Altimate Code change files when it explains a macro? It asks first. When an explanation needs a shell command, such as searching your project for calls to the macro, a Permission required card appears. You choose Allow once, Allow always or Reject. Are there hover actions in schema.yml too? Yes. Hover over a column's name value in schema.yml and two more actions appear: Suggest description and Suggest tests. Both feed the documentation flow in the extension. Does this work in Cursor? Yes. The PowerUser Plugin for dbt installs in Cursor from Open VSX. The hover cards on every ref() and macro call appear the same way as in VS Code. On this page - Hover Over a Model Reference to See Depth and Columns - Hover Over a Macro to See Which Models Use It - Go From the Whole Model Down to One Dependency ## Related Resources PowerUser Plugin for dbt Generate dbt Unit Tests in the Documentation Editor, Next to Your Docs and Data Tests https://altimate.ai/product-highlights/generate-dbt-unit-tests-in-the-documentation-editor PowerUser Plugin for dbt Ask Altimate Code About a dbt Model Straight from the Lineage Graph https://altimate.ai/product-highlights/ask-ai-about-dbt-lineage-in-vs-code PowerUser Plugin for dbt Profile Every CTE in a dbt Model to Find the Join That Inflates Your Rows https://altimate.ai/product-highlights/debug-a-dbt-model-by-profiling-each-cte Blog We Created Data Engineering Skills for Claude Code https://altimate.ai/blog/we-created-data-engineering-skills-for-claude-code ## Install the dbt VS Code Extension. Free to Start. Power User for dbt is an open source VS Code extension that adds column lineage, autocomplete, AI docs, query previews and health checks to your dbt project. [Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=innoverio.vscode-dbt-power-user) [Book a Demo](https://calendly.com/d/ctnv-rbc-yr3/altimate-ai-overview) [Read the docs →](https://help.altimate.ai/dbt-power-user/) The Altimate platform: team spend by warehouse, dbt column lineage and an Altimate Code session recap