In dbt, how do you install the dbt_utils package and call its macros from a model?

## Declaring and installing A dbt package is just another dbt project — models, macros, tests — that you pull into yours. Declare it in `packages.yml` beside `dbt_project.yml`: ```yaml packages: - package: dbt-labs/dbt_utils version: [">=1.1.0", "<2.0.0"] ``` Then `dbt deps` fetches it into the `dbt_packages/` directory. That directory is generated and belongs in `.gitignore`; `packages.yml` is the thing you commit. Every environment — a new laptop, a CI container, a scheduled production run — must execute `dbt deps` before `dbt run`, or macros will resolve to nothing and parsing will fail. Packages can also come from a git URL (with a `revision`) or a local path, which is how teams share an internal macro library across several dbt projects. ## Calling package macros Use the package name as a namespace: ```sql select {{ dbt_utils.generate_surrogate_key(['order_id', 'line_number']) }} as order_line_key, {{ dbt_utils.star(from=ref('stg_orders'), except=['_loaded_at']) }} from {{ ref('stg_orders') }} ``` The prefix is not decorative. Macro names are a flat namespace, and the prefix is what says *this* implementation. If your own project defines a macro called `star`, `{{ star(...) }}` and `{{ dbt_utils.star(...) }}` are different calls; the namespaced form always reaches the package. ## What dbt_utils actually gives you dbt_utils is the near-universal utility package maintained by dbt Labs. The macros worth knowing by name: - `star(from, except=[], relation_alias=...)` — expands to a comma-separated list of a relation's columns, minus the exclusions. It is how you write "select everything except these three" in a warehouse that has no such syntax. Note that it introspects the relation at compile time, so the upstream must exist. - `generate_surrogate_key(['a','b'])` — a deterministic hash across the listed columns, with consistent null handling. This is the standard way dbt projects build a surrogate key. - `date_spine(datepart, start_date, end_date)` — generates a contiguous calendar, the basis of most date dimensions. - `union_relations(relations=[...])` — unions relations whose column sets differ, filling missing columns with nulls. - `get_column_values(table, column, default=[])` — runs the distinct query and returns a list, handling the parse-phase guard for you. - `pivot` and `unpivot` — reshape helpers. It also ships generic tests such as `equal_rowcount`, `expression_is_true` and `accepted_range`, which you reference from YAML the same way as built-in tests; the testing topic covers how those are configured. ## Versioning discipline Two naming shifts illustrate why the range matters. dbt_utils 1.0 renamed `surrogate_key` to `generate_surrogate_key` and moved several cross-database macros (`datediff`, `dateadd`, `safe_cast` and friends) into dbt Core itself, where they are called without a namespace. Around the same time, dbt Core 1.0 changed the install directory from `dbt_modules/` to `dbt_packages/`. A project that floated on the latest version through either transition broke on a routine `dbt deps`. So: pin a range that excludes the next major, upgrade deliberately, and read the package changelog before bumping. `dbt deps` also writes `package-lock.yml` in recent dbt versions, which records the exact resolved versions — commit it if you want reproducible installs across environments. ## When to reach for a package and when not to Installing dbt_utils to get one macro is fine; it is small, ubiquitous and well tested. The judgment call is the opposite direction: teams sometimes install five packages and end up with several overlapping ways to do the same thing, plus a dependency graph they cannot upgrade because two packages pin incompatible ranges of a third. Each package is code you did not write running inside every compile. A reasonable house rule is: dbt_utils by default, a warehouse-specific package where it removes real dialect pain, an internal package for macros shared across your own projects, and everything else justified case by case. And when you find yourself writing a helper macro, check dbt_utils first — the odds are good that the well-tested version already exists and behaves correctly on nulls, which hand-rolled versions frequently do not.