How to Use dbt utils

packages.yml sits next to dbt_project.yml. Pinning to a version range rather than one exact version lets you pick up patch releases without breaking on a major one. Packages install into dbt_packages/, which belongs in .gitignore since it is fully reproducible from this file.

# packages.yml
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<2.0.0"]

dbt deps downloads the package and has to be re-run whenever packages.yml changes, plus on any fresh checkout or CI runner. dbt refuses to compile with a clear error when packages are missing, so this is a required step rather than an optional one.

dbt deps

Surrogate key and date spine

generate_surrogate_key hashes the listed columns into one deterministic key and handles NULLs consistently, so two rows differing only in a NULL do not collide. date_spine generates one row per interval and is the usual base for a calendar dimension, normally wrapped in its own model. Both are namespaced with the dbt_utils. prefix.

SELECT
  {{ dbt_utils.generate_surrogate_key(['customer_id', 'order_date']) }} AS order_key
FROM {{ ref('stg_orders') }}

-- calendar table
{{ dbt_utils.date_spine(
    datepart='day',
    start_date="cast('2024-01-01' as date)",
    end_date="cast('2027-01-01' as date)"
) }}