dbt seedでcsvデータをロードしよう

こんにちは、六本木アナリティクスエンジニアのTaku（@aelabdata ）です。

dbt入門の第4回です。前回は、データモデリング環境構築の実践編で、dbt coreとVS codeとDuckDBのデータモデリング環境構築ができました。

dbt coreとVS CodeとDuckDBで始めるデータモデリング環境構築ガイド（実践編）

今回は、dbtの公式学習プロジェクトである jaffle_shop のサンプルデータを、dbt seed というコマンドを使ってローカルのDuckDBデータベースにロードする具体的な手順を、ハンズオン形式で丁寧に解説していきます。

この記事を読み終える頃には、データモデリングの土台となる最初のデータセットが、あなたの手によって準備されているはずです。それでは早速、dbt seed とは一体何なのか、その基本から見ていきましょう。

dbt seed とは

dbt seed は、単にCSVファイルをデータベースにロードする機能ではありません。これは、dbtプロジェクトにおいて、バージョン管理された静的なデータを分析ワークフローに組み込むための戦略的な仕組みです。

seedsディレクトリに配置されたCSVファイルは、Gitでコードと一緒に管理されるため、変更履歴を追跡でき、チームでのレビューも可能になります。これにより、分析の前提となる小規模なマスタデータなどを、透明性と再現性を持って扱うことができるのです。

 dbt seed の適切な利用シーン

dbt seedは、頻繁には変更されない、比較的小さなデータセットに最適です。以下のようなケースで真価を発揮します。

  • 国コードと国名のマッピングリスト: US を United States に変換するような、分析で頻繁に利用する対応表。
  • 分析から除外するテスト用メールアドレスリスト: test@example.com のような、分析ノイズとなるアカウントの一覧。
  • 従業員のアカウントIDリスト: 社内ユーザーの行動を区別するためのID一覧。
dbt seed の不適切な利用シーン

dbt seedには向いていない使い方もあります。dbtはあくまでデータ変換ツールであり、本格的なデータローダーではないことを理解しておくことが重要です。

  • 本番データベースからエクスポートされた大規模な生データ: dbt seedは大量のデータのロードにはパフォーマンス的に不向きです。このようなデータは、専用のELTツールを使ってデータウェアハウスにロードするべきです。
  • 個人情報（PII）を含む機密データ: seedsディレクトリ内のCSVファイルはGitの永続的な履歴の一部となり、一度コミットしてプッシュしてしまうと機密情報を後から完全に削除することが非常に困難になるため、パスワードや個人情報などの機密データを含めるべきではありません。

dbt seedの役割を理解したところで、次はいよいよ実際の手順に移り、jaffle_shopのデータをあなたのローカル環境に準備しましょう。

dbt seedでcsvデータをロードする

今回、使用するのは、架空のカフェ「Jaffle Shop」のデータで、以下の3つのテーブルを使用します。

  • customers: 顧客のIDや姓名といった顧客情報が格納されています。
  • orders: どの顧客がいつ、どのようなステータスで注文したかという注文情報が格納されています。
  • items: どの注文で、どの商品が購入されたかという注文明細情報が格納されています。

実際にコマンドを実行して jaffle_shop のサンプルデータをローカルのDuckDBにロードしていきます。

この一連の作業は、あらゆるdbtプロジェクトにおいてデータセットを準備するための基本的なフローです。ステップバイステップで進めていきましょう。

ステップ1：作業ブランチの作成

分析プロジェクトでは、コードの変更履歴を管理するためにGitを使用するのが一般的です。新しい作業を始める際には、メインのブランチ（mainなど）から専用の作業ブランチを作成することがベストプラクティスです。これにより、作業中の変更が本番コードに影響を与えるのを防ぎ、安全に開発を進めることができます。

前回のfeat/initial-dbt-setupブランチをGithubでマージしたら、ローカルのmainブランチに変更を反映させましょう。

# メインブランチ（main）に切り替え
git switch main

# リモートから最新の変更を取得
git pull origin main

新しいブランチを作成し、そのブランチに切り替えましょう。

# 新しいブランチを作成し、そのブランチに切り替えます
git switch -c feat/load-jaffle-shop-data

ステップ2：jaffle_shopデータをダウンロード

data-labs/jaffle-shopリポジトリからjaffle_shopのcsvデータをダウンロードして、seedsディレクトリに格納します。

# seedsディレクトリに移動
cd seeds

# raw_customers.csvをダウンロード
curl -O https://raw.githubusercontent.com/dbt-labs/jaffle-shop/main/seeds/jaffle-data/raw_customers.csv

# raw_orders.csvをダウンロード
curl -O https://raw.githubusercontent.com/dbt-labs/jaffle-shop/main/seeds/jaffle-data/raw_orders.csv

# raw_items.csvをダウンロード
curl -O https://raw.githubusercontent.com/dbt-labs/jaffle-shop/main/seeds/jaffle-data/raw_items.csv

# ダウンロードしたファイルを確認
ls

ステップ3：dbt_project.ymlでseedの出力先を設定する

dbt_project.ymlファイルは、dbtプロジェクト全体の設定を管理する、いわば「司令塔」のような存在です。

ここで、dbt seedで作成されるテーブルがデータベースのどのスキーマに出力されるかを定義します。今回は、ロードするCSVデータを「生の（raw）」データと位置づけ、rawスキーマに出力するように設定しましょう。

dbt_project.ymlファイルを開き、以下の設定を追記してください。

dbt_project.yml
...

# Configure seeds
seeds:
  jaffle_shop_tutorial:
    +schema: raw # seedで作成するテーブルはrawスキーマに出力します

+schemaのように設定名の前に+を付けることで、この設定がディレクトリ内のすべてのseedに適用される基本設定（prefix）であることを示します。これにより、後から特定のseedファイルやサブディレクトリで設定を上書き（override）することが可能になり、柔軟なプロジェクト管理が実現できます。

ステップ4：dbt seedコマンドの実行

いよいよデータをデータベースにロードします。dbt seedコマンドを実行すると、dbtはプロジェクトのseedsディレクトリ内にあるすべてのCSVファイルを検出し、それらをテーブルとしてDuckDBデータベース内に作成します。

ターミナルで以下のコマンドを実行してください。

dbt seed

コマンドが成功すると、以下のようなログが出力されます。

$ dbt seed
10:02:59  Found 3 seeds, 5 models, 1 analysis, 3 sources, 611 macros
10:02:59  
10:02:59  Concurrency: 1 threads (target='dev')
10:02:59  
10:02:59  1 of 3 START seed file main_raw.raw_customers .................................. [RUN]
10:02:59  1 of 3 OK loaded seed file main_raw.raw_customers .............................. [INSERT 935 in 0.07s]
10:02:59  2 of 3 START seed file main_raw.raw_items ...................................... [RUN]
10:02:59  2 of 3 OK loaded seed file main_raw.raw_items .................................. [INSERT 90900 in 0.28s]
10:02:59  3 of 3 START seed file main_raw.raw_orders ..................................... [RUN]
10:03:00  3 of 3 OK loaded seed file main_raw.raw_orders ................................. [INSERT 61948 in 1.27s]
10:03:00  
10:03:00  Finished running 3 seeds in 0 hours 0 minutes and 1.73 seconds (1.73s).
10:03:00  
10:03:00  Completed successfully
10:03:00  
10:03:00  Done. PASS=3 WARN=0 ERROR=0 SKIP=0 NO-OP=0 TOTAL=3

ステップ5：DuckDBでロードされたデータを確認する

データが正しくロードされたかを確認することは、データ分析の基本です。dbtには、この確認作業を簡単に行うためのdbt showコマンドが用意されています。SQLクライアントを別途立ち上げることなく、ターミナル上で手軽にテーブルのプレビューができる非常に便利なコマンドです。

raw_customersテーブルを表示してみましょう。

# raw_customersテーブルをプレビュー表示
dbt show --select "raw_customers"

このコマンドの優れた点は、dbtが裏側でデータベース（この場合はDuckDB）に適したSELECT * FROM ...のようなSQLを自動的に生成・実行してくれることです。これにより、データベースの種類を意識することなく、統一されたインターフェースでデータを確認できます。

ヒント

DuckDBでクエリを実行して、データ確認することもできます。DuckDB CLIを起動します。

cd jaffle_shop_tutorial
duckdb jaffle_shop_tutorial.duckdb

DuckDBのプロンプト (D>) が表示されたら、以下のSQLクエリを実行して、dbtが作成したビュー（またはテーブル）が存在することを確認します。

# テーブル一覧を表示
D show tables from main_raw;

# raw_customersのデータを確認
D select * from main_raw. raw_customers;

# DuckDBのCLI終了
D .quit

ターミナルにテーブル形式でデータが表示されれば、ロードは完璧です。 おめでとうございます！これで、データモデリングを開始するためのすべての準備が整いました。

まとめと次のステップ

この記事では、dbt seedコマンドを使い、jaffle_shopのサンプルデータをローカルのDuckDB環境にロードする手順を学びました。静的データの役割を理解し、実際に手を動かして最初のデータセットを準備できました。

次回から、今回ロードしたjaffle_shopデータを用いて、データ分析開発していきましょう！

前の記事

dbt coreとVS CodeとDuckDBで始めるデータモ…

次の記事

成功するdbtプロジェクトの秘訣：3層構造とディメンショナルモ…