dbt_utils パッケージ 最頻出マクロの一覧と使いどころ

dbt の日常運用で最も手に取るパッケージのひとつが dbt_utils です。クロスウェアハウスで安定して動き、モデル記述を短く読みやすくします。

ここでは試験でも実務でも頻出のマクロに絞って、用途・落とし穴・最低限のスニペットをまとめます。公式ドキュメントの一般的で安定した使い方のみを扱います。

頻出マクロ早見表

まずは全体像。試験の設問は「どのマクロを選ぶべきか」を問うことが多いので、ユースケースを軸に俯瞰します。

ここに挙げるマクロは、主要 DWH（Snowflake、BigQuery、Redshift、Databricks/Spark）で広く使われ、API も安定しています。

• generate_surrogate_key: 複合キーのハッシュ化と NULL 耐性
• star: SELECT * を安全に（除外・接頭辞・接尾辞）
• union_relations: 列不一致の UNION 整形
• date_spine: 日付/時間の連続系列生成
• safe_divide: ゼロ割り回避の安全な除算
• unique_combination_of_columns（テスト）: 複合一意制約の検証

packages.yml への追加（前提）

packages:
  - package: dbt-labs/dbt_utils
    version: "+"  # 安定版の範囲指定（プロジェクトの互換性に合わせる）

モデル設計と dbt_utils の位置づけ

dbt_utils はモデリングの反復作業を短縮し、スキーマ変化や DWH 差異に強い SQL を書く助けになります。特に Staging/Intermediate/Mart の各層で役割が明確です。

試験では、どの層でどのマクロを使うと保守性が高いか、という観点がよく問われます。

• Staging: star で生ソースの列展開、generate_surrogate_key で安定キー生成
• Intermediate: union_relations でスキーマ整形、date_spine で系列補完
• Mart: safe_divide で堅牢な率指標、テストで unique_combination_of_columns

dbt モデル層と頻出マクロの対応

ref と Jinja によるマクロ呼び出しの基本形

select
  {{ dbt_utils.star(from=ref('stg_orders'), except=['_ingested_at']) }}
from {{ ref('stg_orders') }}

generate_surrogate_key で安定した複合キーを作る

複数カラムの結合やディメンションの同定に必要なのが代理キーです。generate_surrogate_key はトリムや NULL を吸収して一貫性のあるハッシュ文字列を返します。

ベースの列を変更したらキーも変わるため、ディメンションの SCD 設計とあわせて使い方を固定化しておくと安全です。

• NULL/空白・前後空白の違いをハッシュ前に平準化
• DWH 間で関数差異を吸収（パッケージ側でディスパッチ）
• 長さは実装依存だが、VARCHAR(32〜64) 程度を許容しておくのが無難

典型スニペット（ディメンションの自然キーから代理キー）

with src as (
  select * from {{ ref('stg_customers') }}
)
select
  {{ dbt_utils.generate_surrogate_key([
    'coalesce(country_code, \"\")',
    'customer_id'
  ]) }} as customer_sk,
  *
from src

star と union_relations でスキーマ差分を吸収する

生ソースの列は増減や並び順変更が起こります。star は除外や接頭辞/接尾辞を指定して安全に列展開します。さらに複数テーブルを統合する際は union_relations が列不一致を自動で補完します。

試験では SELECT * の危険性と、star による制御可能な列展開の説明、そして UNION 前整形の手法が問われます。

• star: except=['raw_load_ts'] のように監査列を除外
• star: prefix/suffix で衝突回避（例: prefix='src_')
• union_relations: 欠損列は NULL、余剰列は揃えて投影してくれる

複数ソースを UNION（列不一致を自動調整）

with a as (
  select {{ dbt_utils.star(from=ref('stg_orders_us'), except=['_ingested_at']) }} from {{ ref('stg_orders_us') }}
), b as (
  select {{ dbt_utils.star(from=ref('stg_orders_eu'), except=['_ingested_at']) }} from {{ ref('stg_orders_eu') }}
)
select * from {{ dbt_utils.union_relations(relations=[ref('stg_orders_us'), ref('stg_orders_eu')]) }}

date_spine で欠損日付を埋める

イベントが無い日もレポートに日付行を出したいとき、date_spine で連続系列を生成して左結合します。これにより稼働日での欠測が可視化されます。

開始・終了の境界と粒度を明示し、オフバイワンを避けます。終了日は通常、当日または翌日開始時刻にします。

• datepart は 'day' や 'hour' などを指定
• start_date / end_date は DWH が解釈できる式を文字列で渡す
• 集計対象と LEFT JOIN して欠損ゼロ埋めを実現

日次スパインと売上の結合（ゼロ埋め）

with spine as (
  select * from {{ dbt_utils.date_spine(
    datepart='day',
    start_date="cast('2021-01-01' as date)",
    end_date="current_date"
  ) }}
), sales as (
  select order_date::date as d, sum(amount) as revenue
  from {{ ref('fct_orders') }}
  group by 1
)
select s.date_day as d,
       coalesce(sa.revenue, 0) as revenue
from spine s
left join sales sa on sa.d = s.date_day

テストマクロと安全な派生指標（unique_combination_of_columns / safe_divide）

モデルの品質担保は試験でも実務でも重要です。dbt_utils のテストマクロでビジネスキーの一意性を検証し、集計では safe_divide を用いてゼロ割りを回避します。

特に Looker や BI でゼロ割りエラーや NaN を発生させない実装は、ダッシュボード安定運用の基礎です。

• unique_combination_of_columns: 複合キーの一意性を宣言的に担保
• safe_divide: 分子/分母のいずれかが 0/NULL でも安全に NULL または 0 を返す実装
• 品質テストは CI で自動実行し、回帰を早期検知

YAML テストと安全な除算の例

# models/schema.yml
version: 2
models:
  - name: dim_customer
    tests:
      - dbt_utils.unique_combination_of_columns:
          combination_of_columns: [customer_natural_key, effective_from]

-- models/mart/fct_kpi.sql
select
  date_day,
  {{ dbt_utils.safe_divide(sum(conversions), nullif(sum(sessions), 0)) }} as cr
from {{ ref('fct_sessions') }}
group by 1

問題で確認

よくある質問