dbt Seeds の使い方: CSV から作る静的テーブルの実務と試験対策

Seeds は、プロジェクトに含めた CSV を対象 DWH にテーブルとしてロードする dbt の機能です。外部システムからの変動に左右されない小〜中規模の参照データを、バージョン管理下で提供できます。

この記事では、配置場所、設定、型定義、運用の勘所、他機能との使い分けを押さえ、試験で問われやすいポイントも明確にします。

Seeds の基礎: CSV から安定した参照テーブルを作る

Seeds は、プロジェクトの seeds ディレクトリに置いた CSV を、そのまま DWH 上の物理テーブルとして作成・更新する仕組みです。モデルのように SQL を書かず、CSV の中身がそのまま行データになります。テーブル名は基本的にファイル名（拡張子除く）で決まり、ref('...') で他モデルから参照できます。

ユースケースは、国コードの辞書、カテゴリの正規化、閾値・グルーピングの定義など「静的で共有される小規模データ」。dbt seed コマンドで再現可能に配備でき、CI でも安定して扱えます。

• 配置: プロジェクトの seeds/ 配下（古いプロジェクトでは data/ を使う場合もあります）
• 作成物: 物理テーブル（ビューではない）
• 参照: ref('seed_name') で他モデルから JOIN/フィルタに利用
• CSV はヘッダー行必須。列名がテーブルのカラム名になる
• 型は指定しない限りテキスト系として作成されることが多く、column_types で明示指定が実務では推奨

パイプラインにおける Seeds の位置づけ

最短コマンド

dbt seed
# 特定のファイルだけ
# dbt seed --select path:seeds/countries.csv
# 他モデルから参照（SQL）
# select * from {{ ref('countries') }};

フォルダ構成と dbt_project.yml の基本設定

Seeds はプロジェクトの seeds/ ディレクトリ配下に CSV を置きます。サブディレクトリはそのまま名前空間の整理に使え、テーブル名はファイル名（拡張子除く）です。スキーマや型、識別子のクオート有無などは dbt_project.yml の seeds セクションで設定します。

設定の優先順位は一般のリソースと同様で、より深いスコープ（プロジェクト全体 → パッケージ → ディレクトリ → 個別ファイル）で上書きされます。実務では seeds 専用のスキーマを切る、識別子のクオートを環境に合わせて統一する、型は明示する、の3点を最初に決めると安定します。

• スキーマは +schema で指定（例: reference）。環境別の切替は target.name に応じて schema ルールで制御可
• 列名のクオート（+quote_columns）は DWH によって大小文字や予約語の扱いが変わるため、組織基準に合わせて固定
• 列の型は +column_types で明示（テキスト以外を含む場合は必須に近い）
• CSV はヘッダー行必須。区切り文字は標準はカンマ（必要なら delimiter を使って調整）

dbt_project.yml の例（Seeds 設定）

name: my_project
profile: my_profile

seeds:
  +schema: reference
  +quote_columns: false
  my_project:
    geo:  # seeds/geo/ 配下
      +column_types:
        country_code: varchar(2)
        region: varchar(32)
        is_eu: boolean
    lookup:
      +schema: reference
      # 必要に応じて区切り文字を変更
      # +delimiter: ";"

型定義とロードの挙動: column_types と識別子の扱い

多くのアダプタでは、型を指定しない列はテキスト系（STRING/VARCHAR）として作成されます。計算や結合の安定性を高めるため、数値・日付・真偽値などは column_types で明示しましょう。型名はアダプタ（Snowflake/BigQuery/Databricks など）に合わせて記述します。

列名のクオート（quote_columns）は、識別子の大文字小文字や予約語の扱いに影響します。Snowflake でクオートを有効にすると列名の大小文字が保持され、無効にすると大文字化される、といった差が生じます。組織の命名規約（すべて小文字・アンダースコア等）に合わせ、Seeds とモデルで一貫させてください。

dbt seed を再実行すると、対象テーブルは（アダプタの実装に沿って）再作成または置換され、CSV の内容で上書きされます。増分適用は行われません。

• 実務推奨: すべての非テキスト列は column_types で明示
• 日時・タイムゾーンは DWH の型と比較演算の仕様を事前確認
• 結合キーの空白・NULL・重複は Seeds 側で排除しておく（受験でもよく問われる品質確保）

column_types の最小例

seeds:
  my_project:
    business:
      +column_types:
        id: bigint
        threshold: numeric(10,2)
        valid_from: date
        active: boolean

運用: 更新フロー、環境分離、CI の実践

Seeds の更新は CSV の差分がそのままデータ差分になります。レビューしやすいように小さく保ち、不要な列や空行を含めないのがコツです。大きすぎる Seeds はロード時間と DWH のメンテナンス負荷を増やします（目安として数万〜十数万行を超える場合は、外部ロードや一時ステージ経由の通常モデル化を検討）。

CI/CD では dbt seed を最初期に実行し、依存するモデルを続けて build します。選択子で対象を絞ると高速化できます。権限（grants）が必要なら seeds にも適用ルールを設定してください。

• 小さく、安定した参照データに限定する
• 環境別のスキーマ分離を徹底（prod へはレビュー済み CSV のみ）
• 選択実行: 変更のあったファイル配下だけ seed する
• 依存モデルは dbt build --select +ref('seed_name') で再構築

よく使うコマンド

# すべての Seeds
 dbt seed
# 変更のあった Seeds だけ（例: ディレクトリ指定）
 dbt seed --select path:seeds/geo/**
# Seeds 実行後に依存モデルをビルド
 dbt build --select +ref:countries
# タグで束ねて実行
 dbt seed --select config:tags:static

テストとモデルからの参照: ref とデータ品質

Seeds は他モデルから ref('seed_name') で参照します。辞書テーブルとして JOIN する、受け入れ可能値のリストとして IN で利用するといった使い方が定番です。データテストでは not_null、unique、accepted_values、relationships を Seeds に対しても定義できます。

試験対策としては、静的な参照データは Seeds、可変のソースデータは Sources、履歴保持は Snapshots と区別する設問が頻出です。

• JOIN キーは unique と not_null をセットで担保
• 許容値リストは accepted_values で管理（Seeds を単一の真実源に）
• モデル内では必ず ref を使い、完全修飾名の直書きは避ける

参照とテストの例

-- models/fct_orders.sql
select
  o.order_id,
  o.country_code,
  c.region
from {{ ref('stg_orders') }} as o
left join {{ ref('countries') }} as c
  on o.country_code = c.country_code;

# models/schema.yml（抜粋）
version: 2
seeds:
  - name: countries
    columns:
      - name: country_code
        tests: [not_null, unique]
      - name: region
        tests:
          - accepted_values:
              values: ["EMEA", "AMER", "APAC"]

Seeds と Sources/Snapshots/外部ロードの使い分け

Seeds は「プロジェクト同梱の静的・小規模データ」を素早く安定供給するのに最適です。一方で、外部システム由来の可変データや履歴保持が必要なケース、大規模データには他機能を選ぶのが定石です。

• 静的・小規模・参照用なら Seeds
• 外部DB/オブジェクトストレージ由来で継続取り込みなら Sources + モデル
• 行の版管理や Slowly Changing Dimension なら Snapshots
• 数十万行を超えるデータは外部ロードや ELT パイプラインで取り込み後にモデル化

問題で確認

よくある質問