Find Unused dbt Macros and See Which Models Use Them
Macros are where dbt projects quietly accumulate weight. Someone adds a helper, someone else copies its logic instead of calling it, and a year later nobody knows whether cents_to_dollars is used in one model or forty. The Macros tab answers that from the files, without a dbt run.
What the Macros tab shows
When a project contains macros, the SQL lineage analyzer adds a Macros tab and a Macros count in the stats row. Each macro is a card with:
- Its name, its kind (macro, generic test or materialization), its arguments and the file and line where it is defined.
- A usage badge: used by N tables, test on N tables, used by other macros, used by project settings, dbt calls it itself, or not used here.
- Its description and argument notes, when they are in your YAML.
Expand a card to see the models that use it, the macros that call it, any other files that use it (hooks, for example), and the macro code with line numbers. Click a model to jump to it in the graph.
The other direction
The same information appears from the model side. Select a table and the details panel lists the macros it uses. In the Project files panel, a macro file shows what it defines, and a model file shows the macros it uses. Whichever way you arrive, you can move to the other.
Find the macros nothing uses
Use the Unused filter. It lists macros that no model, test, macro, hook or configuration appears to call. For a first cleanup pass this is exactly what you want: a short list of candidates.
The word is "candidates" on purpose. Before you delete anything:
- Search your other repositories. A macro in a shared package may be used by projects this folder does not contain, which is why a package such as dbt-utils shows many macros as not used here.
- Remember macros can be called by a string, for example through run_query or dispatch built from a variable. Usage is found by looking for the call in the text, so a macro invoked by a built name cannot be seen.
- Check scheduled jobs and operations (dbt run-operation), which are outside the project files.
Things it knows so it does not cry wolf
A naive search would flag many macros as unused when they are not. These cases are handled:
- Adapter versions such as default__x or postgres__x are shown inside the macro that dispatches to them, not as separate, unused entries.
- Macros that dbt calls by itself, such as generate_schema_name, are labelled as such.
- Macros used by hooks in dbt_project.yml count as used.
- A materialization chosen with materialized='name' counts as used.
- A generic test is linked to the models whose YAML declares it.
Before you change a macro
Expand the macro in the Macros tab to see how many models use it, so you can size the change before you start. Then edit one of those models in the SQL lineage analyzer to see what a change would break downstream. See check what a dbt change breaks before you merge.
Limits
Macros are not drawn as nodes in the graph. They live in their own tab and in the panels. What a macro expands to is not computed, so the lineage of a column built by a macro that generates columns is not followed. And since nothing is executed, there is no way to know whether a macro is called at run time through a name built from strings.
Related tool pages
- dbt Lineage Viewer for Your SQL Models: Drop your dbt models folder and see the lineage graph from sources through staging to marts, with column links. No dbt run, no warehouse. Free, private.
- SQL Column Lineage Tool: See which source columns build every column of a view or table across many SQL files. Trace to the raw table or forward to dependants. Free, in your browser.
- SQL File Dependency Analyzer: Find out which SQL file must run before which, from the tables each file creates and reads. Get a run order, circular dependencies and tables nothing uses.
- SQL Impact Analysis: What Breaks If a Table Changes: Pick a table and see everything downstream that depends on it, and every upstream source it is built from. Works across a whole folder of SQL files, free.
- SQL File Lineage Tool: Free SQL file lineage tool: drop a folder of .sql files and see which file feeds which table, column by column. Nothing is uploaded.
- SQL Query Visualizer: Free SQL query visualizer: paste a query or drop SQL files and see tables, joins and columns as a clear diagram. Runs in your browser, no upload.
Also try
How to use the SQL Lineage Analyzer: step by step
- Load your dbt project, including the macros folder.
- Open the Macros tab and choose Unused to see candidates for removal.
- Expand a macro to see the models that use it before you change it.
When to use the SQL Lineage Analyzer
- Clean up unused macros
- Find every model that uses a macro before changing it
- Review macro changes in a pull request
- Understand what custom logic a project depends on
Example
Input: models/ folder: raw schema, staging views, marts, reports (7 .sql files)
Output: A graph of 10 tables and views, 40 column links and the order to run the files
Frequently asked questions
How do I find unused dbt macros?
Load your project in the SQL lineage analyzer, open the Macros tab and choose Unused. It lists macros that no model, test, macro, hook or setting appears to call.
How do I see which models use a macro?
Open the Macros tab and expand the macro. It lists the tables that use it, and you can click one to open it in the graph.
Is "not used here" always safe to delete?
No. A macro may be used by another project, called by a name built from strings, or run by a scheduled operation. Treat the list as candidates and search your other repositories before deleting.
Does it understand adapter-specific macros?
Yes. Versions such as default__x and postgres__x are grouped under the macro that dispatches to them.
Tip: Search all your repositories for a macro name before deleting it. A package may be used by projects this folder does not include.