dbt-utils is the most depended-on package in the dbt ecosystem. It includes 50+ macros and generic tests covering SQL generation, data introspection, quality validation, and cross-warehouse compatibility.
These notes cover dbt-utils v1.3.3, compatible with dbt Core 1.x and dbt Fusion 2.x.
Before You Start
The most common source of confusion with dbt-utils is which macros still live in the package and which moved to dbt-core. Since v1.0, all cross-database macros (dates, strings, type casting) moved to the dbt.* namespace. Start with the migration note when working on an older codebase or upgrading from v0.x.
Reading Order
dbt-utils v1.0 Migration: What Moved to dbt-core
The complete list of macros removed from dbt-utils and moved to dbt.*, what was removed entirely (old surrogate_key(), unique_where, not_null_where), and the step-by-step migration path. Read this first if you’re upgrading.
dbt-utils SQL Generators
The most commonly used part of the package: date_spine, deduplicate, star, union_relations, pivot, unpivot, and the smaller helpers (group_by, safe_divide, haversine_distance, etc.). These generate SQL at compile time without querying the database.
dbt-utils generate_surrogate_key
The hash-based surrogate key macro deserves its own note because of the null handling gotcha that can silently break incremental models when migrating from the old surrogate_key() macro. Read this before touching surrogate keys in an existing project.
dbt-utils Introspective Macros
Macros that query the database at compile time: get_column_values, get_relations_by_pattern, get_query_results_as_dict, get_single_value, get_filtered_columns_in_relation. Powerful but require the target relations to already exist.
dbt-utils Generic Tests
The full generic test reference with YAML examples. Covers the Fusion/dbt Core 1.10.6+ arguments: syntax change, the group_by_columns parameter for segmented validation, and when to use each test.
dbt-utils Web Macros for URL Parsing
The URL extraction trio (get_url_host, get_url_path, get_url_parameter) and the Jinja development helpers. Niche but useful in marketing analytics.
Prerequisites
You should have dbt-utils installed and be comfortable with basic Jinja in dbt models. The dbt Macros note covers Jinja fundamentals if you need a refresher on how macros work under the hood.
For non-standard adapters (Databricks, Spark), you may need additional dispatch configuration. See dbt Dispatch Configuration and the note on dbt Built-In Cross-Database Macros for context.