🪿

dbt Core + DuckDB

に公開
2026/08/14

本記事はdbt Advent Calendar 2025 18日目に寄稿した記事となります。

☕️Ice Break

最近、DuckDBに入門しました。

https://x.com/kazuya_araki_jp/status/1983149662602453000?s=20

業務活用を想定してキャッチアップしてみた感想ですが、現状の業務に活かせる環境というよりは、SQLとdbt Core初学者用のSandboxとしての可能性を感じています。

💨TL;DR: 急いでいる人向けのまとめ

  • 🛠️環境構築は特に難しくない。
  • 🪿CSV to DuckDBを試してみた。
    • Preppin' DataをTableau Prepではなく、dbt Core + DuckDBで解いてみた事例を紹介します。
    • 環境構築が完了すれば、無料でData Warehouse周辺の基礎的な技術を習得できる学習環境として非常に役立ちます。

🛠️Setup dbt Core and DuckDB

Setup concept

  • 可能な限り、SQLとdbt Coreの学習に注力できるような環境構築を目指してみます。
    • DockerやKubernetesで動作環境を用意するのが定石の一つですが、これらのツールの学習コストはSQLやdbt Coreとは別物なので、避けたい。
    • 特に、データアナリストやデータサイエンティストといった職種の方の平均的なスキルセットを鑑みると、インフラ関連のスキルはtoo muchであると判断[1]。
    • 以上により、Pythonと親和性の高いuvを用いたdbt環境を選定。
  • [超大事]可能な限り、コード化する。
    • 再現性、冪等性を確保するため。
      • (主に、手がけたものをすぐ忘れる自分向けなのですが)異なる環境でも動作可能な状態を狙う。
      • 本業や副業案件で横展開可能なような状態が理想。

Requirements

Requirements Remarks
macOS Tahoe 26+ 執筆時点(2025年12月18日現在)の最新OSバージョン。
Windows OSは未検証です。
Windows OSの環境で導入したい場合は、OS依存している箇所(e.g. ディレクトリ構成)を適宜読み替えて実施してみてください。
ただし、その際の動作保証は致しかねます。
Apple M1+ CPU not Intel Mac
筆者のPCはM3 Maxで動作確認しています。
zsh macOS 10以降の標準シェル。
bash, fishでも動作できると思いますが、検証が面倒なので動作保証は致しかねます。

Homebrew settings

Basic

Homebrewの基本的なインストールはuvを使ったdbt Coreの導入手順 - Homebrew settingsで解説している通りなので割愛。

Install DuckDB

DuckDBをインストールします。[2]

brew install duckdb

uv settings

Create Python Project

Pythonプロジェクトを作成します。

mkdir ~/Development
cd ~/Development
uv init example_dbt_duckdb_project --python=">=3.13" --bare

Install Python with uv

2025-12-18現在、Python 3.13系の最新バージョンを確認します。

uv python list --all-versions | grep -e "3\.13\."

# Results(as of December 18, 2025)
# cpython-3.13.11-macos-aarch64-none                  <download available>
# cpython-3.13.11-macos-aarch64-none                  <download available>
# cpython-3.13.11+freethreaded-macos-aarch64-none     <download available>
# cpython-3.13.10-macos-aarch64-none                  <download available>
# cpython-3.13.10+freethreaded-macos-aarch64-none     <download available>
# ...

Python 3.13系の最新バージョンをインストールします。

# Template
uv python install {{ latest-version-of-python-3.13-series }}

# e.g.
uv python install 3.13.11

Pin to a specific Python version

Pythonバージョンを固定します。

cd ~/Development/example_dbt_duckdb_project
uv python pin 3.13.11

Install Python packages

dbt Core関連のPythonパッケージをインストールします。
Data PlatformはDuckDBを使用します。

cd ~/Development/example_dbt_duckdb_project
uv add dbt-core dbt-duckdb

Create virtual environment(.venv)

uv add の段階で仮想環境が作成されていますが、もし仮想環境が作成されていない場合は手動で仮想環境を作成します。

cd ~/Development/example_dbt_duckdb_project
uv sync

以上までの手順で、ディレクトリ、ファイルは以下の構成となります。

~/Development
    ┗ example_dbt_duckdb_project
        ┣ .venv/          : 仮想環境
        ┣ .python-version : Pythonバージョンを管理するファイル
        ┣ pyproject.toml  : Python構成ファイル
        ┗ uv.lock         : プロジェクトの依存関係を管理するロックファイル

DuckDB settings

Create Persistent Database

DuckDBのデータベースは永続化データベースとインメモリデータベースがあります。
今回は永続化データベースを使用します。

# Template
duckdb {{ any directory }}/{{ database name }}.db

# e.g.
cd ~/Development/example_dbt_duckdb_project
mkdir databases
duckdb databases/example.db

dbt Core settings

Initialize dbt project

dbtプロジェクトを作成します。

# Template
cd {{ any directory }}
uv run dbt init {{ dbt_project_name }} --profiles-dir ./

# e.g.
cd ~/Development/example_dbt_duckdb_project
uv run dbt init example_dbt_duckdb_project --profiles-dir ./

## Results(as of December 18, 2025)
# HH:MM:SS  Running with dbt=1.10.17
# HH:MM:SS  
# Your new dbt project "example_dbt_duckdb_project" was created!
#
# For more information on how to configure the profiles.yml file,
# please consult the dbt documentation here:
#
#   https://docs.getdbt.com/docs/configure-your-profile
#
# One more thing:
#
# Need help? Don't hesitate to reach out to us via GitHub issues or on Slack:
#
#   https://community.getdbt.com/
#
# Happy modeling!
#
# HH:MM:SS  Setting up your profile.
# Which database would you like to use?
# [1] duckdb
#
# (Don't see the one you want? https://docs.getdbt.com/docs/available-adapters)
#
# Enter a number: 1
# HH:MM:SS  Profile example_dbt_duckdb_project written to profiles.yml using target's sample configuration. Once updated, you'll be able to start developing with dbt.

2025年12月18日現在、 dbt init の挙動が微妙[3]なので、以下を行います。

cp -r ./example_dbt_duckdb_project/* ./
rm -rf example_dbt_duckdb_project

以上までの手順で、ディレクトリ、ファイルは以下の構成となります。

~/Development
    ┗ example_dbt_duckdb_project
        ┣ .venv/          : 仮想環境
        ┣ analyses/       : dbt initで生成されたディレクトリ
        ┣ databases/      : DuckDBの永続化データベースを格納するディレクトリ
        ┣ logs/           : dbt initで生成されたディレクトリ
        ┣ macros/         : dbt initで生成されたディレクトリ
        ┣ models/         : dbt initで生成されたディレクトリ
        ┣ seeds/          : dbt initで生成されたディレクトリ
        ┣ snapshots/      : dbt initで生成されたディレクトリ
        ┣ tests/          : dbt initで生成されたディレクトリ
        ┣ .python-version : Pythonバージョンを管理するファイル
        ┣ dbt_project.yml : dbt initで生成されたファイル
        ┣ profiles.yml    : dbt initで生成されたファイル
        ┣ pyproject.toml  : Python構成ファイル
        ┣ uv.lock         : プロジェクトの依存関係を管理するロックファイル
        ┗ README.md       : dbt initで生成されたファイル

🪿Solve Answer Preppin' Data using dbt and DuckDB

dbt CoreとDuckDBの環境を構築できたので、次にデータ処理の基礎を学べる環境を考えてみます。
取り扱うテーマは何でも良いですが、今回はTableau界隈で認知のあるPreppin' DataをTableau Prepではなく、dbt CoreとDuckDBを用いて解いてみることにします。

What is Preppin' Data?

データ分析の準備段階である「データ構造の最適化」や「整形」のスキルを磨くための、世界的なコミュニティ・プロジェクトです。
毎週新しい課題が提供され、参加者はデータをより扱いやすい形に整える技術を、楽しみながら習得することができます。

  • データ整備力を養う
    • Input: 実務想定のユースケースに基づいたデータセットが公開される。
    • Requirements: データセットの要件を定義している。
    • Output: 上記データセットのデータを加工した結果を示している。
  • 多様なツールに対応
    • 発足当初はTableau Prepを想定していた。
    • 現在は、SQL、Python (Pandas)、Excel、Power Queryなど、データ前処理ツール限定せずに各々自由にツールを選んで挑戦が可能。
  • 学びの共有
    • 自分の回答はX等のSNSで公開し、世界中のデータ利活用者と繋がることが可能。
    • 翌週に公式から回答とフィードバックが公開される。
    • 自分の回答と公式の回答を比較検討することで、より効率的で簡潔なデータ処理の方法を学ぶことが可能。

How to Participate in Preppin' Data

  1. 特別な手続きは一切不要。今すぐにでも始められます。
  2. Preppin' Data - The Challenge Indexから取り組みたい課題を確認する。
  3. 課題のデータセットをダウンロードする。
  4. お好みのツールでデータセットを加工し、指定された出力結果を目指す。
  5. 3ができたら以下を行う。[4]
    1. Preppin' Data Challenge Trackerに完了報告を登録する。登録内容はChallenge Trackerに反映される。
    2. 回答をXにシェアする。 #PreppinData へのタグ付けや @Datajedininja , @JennyMartinDS14 , @TomProwse1 へのメンションを忘れずに。

Solving Preppin' Data Challenge using dbt and DuckDB

Strategy

回答するにあたり、dbtとDuckDBのデータアーキテクチャを以下のように設計してみました。

dbt Asset DuckDB Asset Description
models/pd_yyyy pd.yyyy スキーマ名。
yyyy: Preppin' Data課題公開年
models/pd_yyyy/pd__yyyy__week_n__input[_num] pd.yyyy.week_n__input[_num] 入力データテーブル。
yyyy: Preppin' Data課題公開年
n: Preppin' Data課題の週数
_num: 入力データが複数ある場合は連番で命名。採番の必要がなければ _num の命名は不要。
models/pd_yyyy/pd__yyyy__week_n__intermediate[_num] pd.yyyy.week_n__intermediate[_num] 中間データテーブル。
yyyy: Preppin' Data課題公開年
n: Preppin' Data課題の週数
_num: 中間データが複数ある場合は連番で命名。採番の必要がなければ _num の命名は不要。
models/pd_yyyy/pd__yyyy__week_n__output[_num] pd.yyyy.week_n__output[_num] 回答データテーブル。
yyyy: Preppin' Data課題公開年
n: Preppin' Data課題の週数
_num: 回答が複数ある場合は連番で命名。採番の必要がなければ _num の命名は不要。

https://github.com/kazuya0araki/dbt-duckdb-preppin-data

e.g. 2024: Week 1 - Prep Air's Flow Card

Requirements

(ざっくり機械翻訳)
Prep Air の航空会社データを整形し、次のデータを作成すること。

  1. 入力データを取得する。
  2. Flight Details を以下のように分割してフィールドを作成する。
    • Date
    • Flight Number
    • From
    • To
    • Class
    • Price
  3. 以下のフィールドを適切なデータ型に変換する。
    • Date → 日付(Date)型
    • Price → Decimal(数値)型
  4. Flow Card の値を変換する。
    • 1 -> Yes
    • 0 -> No
  5. Flow Card 保有者と非保有者でテーブルを分割する。(最終成果物)
    • Output 1: Flow Card 保有者のフライト詳細データ
    • Output 2: Flow Card 非保有者のフライト詳細データ

Solution

回答の解説は割愛しますが、多少のPythonとSQLだけで回答できました。

入力データ: pd__2024__week_1__input(Python model)

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/pd__2024__week_1__input.py

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/_pd__2024__week_1__input.yml

中間データ: pd__2024__week_1__intermediate(SQL model, view materialization)

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/pd__2024__week_1__intermediate.sql

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/_pd__2024__week_1__intermediate.yml

回答データ:

Output 1: pd__2024__week_1__output_1(SQL model, table materialization)

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/pd__2024__week_1__output_1.sql

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/_pd__2024__week_1__output_1.yml

Output 2: pd__2024__week_1__output_2(SQL model, table materialization)

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/pd__2024__week_1__output_2.sql

https://github.com/kazuya0araki/dbt-duckdb-preppin-data/blob/main/models/pd__2024/_pd__2024__week_1__output_2.yml

📚Conclusion

冒頭にも書きましたが、DuckDBをローカルPCで起動し、dbtを業務で使うイメージはあまり実感がありません。もう少し業務利活用できないか模索してみます。
それよりも業務利用以上に学習環境としては非常に可能性のある環境だと思いました。データモデリング、データエンジニアリングの基礎やSQLの習得といった、データ全般の業務の基礎的な技術をノーコストで構築できる点は非常に魅力的です。

最後に、Preppin' Dataについて取り上げましたが、気が向いたら回答解説シリーズを連載してもいいかもしれません。
Tableau Prep他ETLツールを使い続けているだけだと、ツールに依存してしまう懸念があります。どうしても習得が難しいデータモデリングの箇所であったり、ツール特有の技術(Tipsのようなものや公式ドキュメントに乗らない挙動や機能)を習得する必要があったりするためです。特にTableau Prepしか使ってこなかった方々に対しては、中長期のデータキャリアを見据えて本件にトライしてみるのもいかがでしょうか?
(と、紹介しているのもdbtやDuckDBといった商用ツールではあるので、いつまで通用するかは分かりませんが、少なくともSQLは二十数年は使えてきている技術ではあるので、SQLを習得して損はないと私が保証します)

APPENDIX

脚注
  1. ただし、この判断を企業ないし組織で判断する際は、背景が全く異なるので、今回の手法にこだわる必要はありません。 ↩︎

  2. DockerやKubernetesを使用する際はDuckDBを別コンテナで作成する方が定石ですが、今回は横着してOSインストールを試みています。 ↩︎

  3. ↩︎
  4. 任意なので未対応でも特に問題はありませんが、モチベーションを維持するために対応した方がいいと思います。 ↩︎

Discussion