dbt の source() 関数を正しく使う：Sources のメリットと試験対策

dbt で生データを参照するとき、直接テーブル名を書かずに source() を使うのが定石です。これは見た目の書き方の違いだけでなく、環境可搬性、ドキュメント、リネージ、テスト、新鮮度管理まで効く重要な選択です。

本記事では、dbt の Sources 定義と source() 関数の基本、導入メリット、定義のベストプラクティス、テストと新鮮度チェック、運用パターン、資格試験で問われやすい観点をまとめます。

source() の基本と役割

source() は、dbt で管理していない外部テーブル（生データなど）を参照するための Jinja 関数です。呼び出しは source('source_name', 'table_name') の2引数で、両者は YAML の sources 定義で宣言した name に一致します（実テーブル名が別名なら identifier でマッピングします）。

ref() は dbt がビルドするモデル間の依存を表現し、source() は外部データに対する依存を表現します。どちらも dbt のリネージグラフに反映され、コンパイル時に正しいデータベース・スキーマ・テーブル名へ解決されます。

• 使いどころ: DWH に既存の生テーブル（例: 原始ログ、SaaS 連携テーブル）を参照するモデル
• 避けるべき: 外部テーブルをスキーマ付きで直書き（環境差分に弱く、リネージに載らない）
• YAML 上の name と実テーブル名の差異は identifier で吸収（リネージの可読性を確保）

リネージの全体像（Sources → Staging → Marts）

Sources を使うメリット（環境可搬性・リネージ・テスト・新鮮度）

Sources を定義して source() で参照すると、環境に依存しない解決、リネージとドキュメントの自動生成、ソースレベルのテストと新鮮度チェック、権限や命名の差異吸収（identifier）が一度に得られます。これは実務でも試験でも最頻出の評価ポイントです。

特に新鮮度（freshness）は Sources 特有の機能で、最新取り込み時刻を監視し、遅延を早期検知できます。可観測性の起点として Sources をきちんと定義しておくのが中長期のコスト最適です。

• 環境可搬性: database/schema の差異を YAML で吸収、Jinja は常に source() で統一
• リネージ・ドキュメント: dbt docs に Sources と依存関係が反映される
• テスト: not_null, unique 等のテストをソース列に付与可能
• 新鮮度: warn_after / error_after と filter で監視対象を制御可能

定義方法とベストプラクティス

Sources は schema.yml（version: 2）で宣言します。source: name は論理名、tables[].name は source() の第2引数で使う論理名です。実テーブル名が異なる場合は identifier を指定します。database や schema は target ごとに上書きされる戦略（env/vars）を併用することも多いです。

ベストプラクティスとして、raw のような着地点ごとに source を分け、説明やオーナー、読み取り権限の所在を docs ブロックや meta に明記します。外部システム起因の取り込み遅延がある場合は freshness の filter で当日分などに絞ると誤検知を避けられます。

• name は論理名、identifier は実テーブル名（混同しない）
• 説明・責任者・SLA は docs/meta に記載
• database/schema は target 変数や profiles.yml で環境差分を吸収
• クエリ負荷を抑えるため、不要列は下流の stg モデルで選別

YAML での Sources 定義と model からの参照例

# schema.yml（version: 2）
version: 2
sources:
  - name: raw          # 論理名（source() 第1引数）
    database: {{ target.database }}   # 環境ごとに解決
    schema: raw
    description: 原始取り込み領域（外部管理）
    freshness:
      warn_after: {count: 2, period: hour}
      error_after: {count: 6, period: hour}
      filter: "_ingested_at >= dateadd('day', -1, current_timestamp())"
    tables:
      - name: orders_raw      # 論理名（source() 第2引数）
        identifier: ext_orders # 実テーブル名
        loaded_at_field: _ingested_at
        columns:
          - name: order_id
            tests:
              - not_null

-- models/stg_orders.sql
with src as (
  select *
  from {{ source('raw', 'orders_raw') }}
)
select
  cast(order_id as string) as order_id,
  customer_id,
  order_ts,
  _ingested_at
from src;

テストと新鮮度チェック（dbt test / dbt source freshness）

ソース列への not_null や unique などの汎用テストは、通常のモデル列テストと同様に YAML で宣言します。dbt test を実行するとソース列も検証対象となり、異常は早期に検知されます。

新鮮度は dbt source freshness コマンドで評価されます。loaded_at_field を基準に現在時刻との差を測り、warn_after / error_after を超えた場合にステータスが変わります。filter を使い、派生ビューや長期履歴を除外して当日分のみを対象にするなど、実データの性質に合わせてチューニングします。

• dbt test: 列品質の担保（null 混入などの早期検知）
• dbt source freshness: 取り込み遅延の監視（SLA 逸脱検出）
• loaded_at_field は時刻型が推奨、文字列なら適切にキャストできるように
• スケジューラでの定期実行時は結果をアーティファクトとして保存し可視化（dbt docs に反映）

運用パターンとアンチパターン

安定運用の基本は「Sources で外部を明示」「stg レイヤで整形」「上位は ref() で接続」の三層です。環境やアダプタ（Snowflake/Databricks/BigQuery 等）の差異は Sources と profiles.yml 側で解消し、モデルは常に source()/ref() で抽象化します。

避けるべきは、スキーマ直書きや、実テーブル名の変更を前提にした脆い依存です。identifier を使えば命名の差分を吸収でき、下流への影響を最小化できます。

• 推奨: raw → stg → marts の三層、外部は source()、内部は ref()
• 推奨: identifier で実名差分吸収、name はビジネス的な論理名に
• 非推奨: スキーマ直書き、環境固有の DB 名をモデルに埋め込む
• 非推奨: loaded_at_field 未設定で新鮮度監視を諦める

Analytics Engineer 試験対策の要点

試験では、source() と ref() の使い分け、Sources の YAML 定義（name と identifier の役割、loaded_at_field、freshness）が頻出です。また、環境可搬性やリネージに関する設問で、スキーマ直書きが不正解になるパターンが多い点に注意します。

コード断片の読み取りでは、source() の2引数が YAML の name を参照しているか、freshness の warn_after/error_after の意味、filter の影響範囲などを把握しているかが問われやすいです。

• 外部データは source()、内部モデルは ref()
• name と identifier を取り違えない（source() は name を参照）
• freshness は loaded_at_field を前提に評価される
• 直書きはリネージに載らず不正解になりやすい

問題で確認

よくある質問