7
7

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@ktdatascience

【dbt × Snowflake】初めてのdbtプロジェクトで押さえておきたい用語集

7
Posted at

はじめに

この記事は、dbt（data build tool）を初めて触る方に向けた用語集です。
Snowflake をデータウェアハウスとして使い、dbt でデータ変換パイプラインを構築するシーンを想定しています。

「公式ドキュメントを読み始めたけど、用語が多くてつまずいた…」という方の最初の一歩になれば幸いです。

dbt とは何か

dbt は SELECT文を書くだけでデータウェアハウス上のテーブルやビューを作成・管理できるデータ変換ツールです。
従来のETL（Extract → Transform → Load）のうち "T（Transform）" の部分を担います。SQLを書ける人であれば、ソフトウェアエンジニアリングのベストプラクティス（バージョン管理・テスト・ドキュメント）をデータ変換に適用できるのが最大の特長です。

image.png

dbt の基本用語

dbt Core / dbt Cloud

用語 説明
dbt Core OSSとして提供されるCLIツール。ローカル環境やCI/CDパイプラインから dbt run などのコマンドを実行する。無料。
dbt Cloud dbt Labs社が提供するSaaS。ブラウザ上のIDEやジョブスケジューラ、CI機能などが組み込まれている有償サービス（無料プランあり）。

初学者はまず dbt Core をローカルにインストールして触ってみるのがおすすめです。

Profile（profiles.yml）

dbt がデータウェアハウスに接続するための 認証情報・接続先を定義するファイルです。
Snowflakeの場合、account・user・password・warehouse・database・schema などを記述します。

~/.dbt/profiles.yml
my_project:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: xy12345.ap-northeast-1.aws
      user: my_user
      password: "{{ env_var('DBT_PASSWORD') }}"
      warehouse: TRANSFORM_WH
      database: ANALYTICS
      schema: DEV
      role: TRANSFORM_ROLE
      threads: 4

profiles.yml には認証情報が含まれるため、Git にコミットしないよう注意してください。env_var で環境変数から読み込む方法が推奨されています。

Project（dbt_project.yml）

dbtプロジェクト全体の 設定ファイルです。プロジェクト名、モデルごとのデフォルト Materialization（後述）、ディレクトリパスなどを定義します。

dbt_project.yml
name: 'my_project'
version: '1.0.0'

profile: 'my_project'

model-paths: ["models"]
seed-paths: ["seeds"]
test-paths: ["tests"]
macro-paths: ["macros"]

models:
  my_project:
    staging:
      +materialized: view
    marts:
      +materialized: table

Model

dbt における最も基本的な構成単位です。1つのModelは 1つのSQLファイル（.sql） に対応し、実行するとSnowflake上に テーブルまたはビュー が作られます。

models/staging/stg_orders.sql
with source as (
    select * from {{ source('raw', 'orders') }}
)

select
    id          as order_id,
    user_id,
    status,
    created_at
from source

ファイル名がそのまま Snowflake 上のテーブル名/ビュー名になります（例: stg_orders.sql → STG_ORDERS）。

Materialization（マテリアライゼーション）

Model の実行結果を どのような形式で Snowflake 上に保存するか を制御する設定です。

image.png

ref 関数

他の Model を参照するための dbt 固有の関数です。ref() を使うことで、dbt がモデル間の 依存関係（DAG）を自動で解決 してくれます。

-- stg_orders モデルを参照する
select * from {{ ref('stg_orders') }}

ref() を使わずに直接テーブル名を書くと、依存関係が認識されず、実行順序やリネージが正しく管理できなくなります。Model 間の参照には必ず ref() を使いましょう。

source 関数

dbt の管理外にある 生データ（ソーステーブル）を参照する関数です。source() を使うことで、ソースに対しても鮮度チェック（Freshness）やドキュメント管理を適用できます。

select * from {{ source('raw', 'orders') }}

ソースの定義は YAML ファイルに記述します。

models/staging/_sources.yml
sources:
  - name: raw
    database: RAW_DB
    schema: PUBLIC
    tables:
      - name: orders
      - name: customers

プロジェクト構成に関する用語

staging / intermediate / mart（レイヤー設計）

dbt プロジェクトでは、Model を役割ごとのレイヤー（層）に分けて整理するのがベストプラクティスです。

レイヤー 役割 命名規則の例
staging ソースデータをそのまま取り込み、カラム名の統一やリネームなど最小限の整形を行う。1ソーステーブル = 1 staging Model。 stg_<source>__<table>
intermediate staging を組み合わせた中間的なビジネスロジックを記述する。 int_<entity>__<verb>
mart BIツールやアナリストが直接参照する最終的な分析用テーブル。ビジネス上の意味を持つ粒度で集計・結合される。 fct_<entity> / dim_<entity>
ディレクトリ構成の例
models/
├── staging/
│   ├── _sources.yml
│   ├── _stg_models.yml
│   ├── stg_raw__orders.sql
│   └── stg_raw__customers.sql
├── intermediate/
│   └── int_orders__pivoted.sql
└── marts/
    ├── _mart_models.yml
    ├── fct_orders.sql
    └── dim_customers.sql

schema.yml（YAML定義ファイル）

Model や Source の メタデータ（説明文・テスト・カラム定義）を記述する YAML ファイルです。ファイル名は自由ですが、_<レイヤー名>_models.yml や schema.yml とすることが多いです。

models/staging/_stg_models.yml
version: 2

models:
  - name: stg_raw__orders
    description: "受注データの staging モデル"
    columns:
      - name: order_id
        description: "注文を一意に識別するID"
        tests:
          - unique
          - not_null

Seed

CSVファイルを dbt 経由で Snowflake のテーブルとして取り込む機能です。マスターデータやマッピングテーブルなど、小規模で変更頻度の低いデータに適しています。

seeds/
└── country_codes.csv

dbt seed コマンドを実行すると、CSV の内容がそのままテーブルとして Snowflake 上に作成されます。

Macro

Jinja テンプレートで書かれた再利用可能な SQL スニペットです。繰り返し出てくるロジックを関数化して DRY（Don't Repeat Yourself）に保てます。

macros/cents_to_dollars.sql
{% macro cents_to_dollars(column_name) %}
    ({{ column_name }} / 100)::numeric(16,2)
{% endmacro %}

Model での使用例:

select
    order_id,
    {{ cents_to_dollars('amount_cents') }} as amount_dollars
from {{ ref('stg_raw__orders') }}

Package（packages.yml）

サードパーティ製の dbt パッケージ（Macro やテストの集合）を導入する仕組みです。packages.yml に記述し、dbt deps コマンドでインストールします。

packages.yml
packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.1
  - package: calogica/dbt_expectations
    version: 0.10.1

dbt_utils は多くのプロジェクトで使われる定番パッケージで、surrogate_key（サロゲートキー生成）や pivot（ピボット変換）など便利な Macro が揃っています。

データ品質・テストに関する用語

Generic Test（汎用テスト）

dbt に 組み込みで用意されている4種類のテストです。YAML ファイルにカラム名と一緒に宣言するだけで使えます。

テスト名 検証内容
unique カラムの値が一意であること
not_null NULL 値が存在しないこと
accepted_values 指定した値のリストのいずれかであること
relationships 他のテーブルのカラムに存在する値であること（参照整合性） 
columns:
  - name: status
    tests:
      - not_null
      - accepted_values:
          values: ['pending', 'shipped', 'delivered', 'returned']
  - name: customer_id
    tests:
      - relationships:
          to: ref('dim_customers')
          field: customer_id

Singular Test

カスタムSQLで記述する一点もののテストです。tests/ ディレクトリに SQL ファイルを置きます。クエリの結果が 0行であればテスト成功、1行以上返ればテスト失敗です。

tests/assert_positive_order_amount.sql
-- 注文金額が0以下のレコードが無いことを確認する
select
    order_id,
    amount
from {{ ref('fct_orders') }}
where amount <= 0

dbt test コマンド

# すべてのテストを実行
dbt test

# 特定のモデルに関連するテストだけ実行
dbt test --select stg_raw__orders

テストが失敗すると、該当レコードの情報とともにエラーが表示されます。CI/CD に組み込むことで、マージ前にデータ品質を自動チェックできます。

ドキュメント・リネージに関する用語

description

Model やカラムに付与できる説明文です。schema.yml の description フィールドに記述します。ここに書いた内容は、後述の dbt docs で生成されるドキュメントサイトに反映されます。

dbt docs generate / dbt docs serve

# ドキュメントを生成（JSONファイル群が出力される）
dbt docs generate

# ローカルサーバーを起動してブラウザで閲覧
dbt docs serve

dbt docs serve を実行すると、モデルの一覧・カラム定義・テスト結果・リネージグラフなどを閲覧できるWebサイトがローカルに立ち上がります。

DAG（有向非巡回グラフ）

Directed Acyclic Graph の略で、dbt が管理するモデル間の依存関係を表すグラフ構造です。ref() や source() の関係から自動的に構築されます。

dbt はこの DAG に基づいて正しい順序でモデルを実行します。たとえば fct_orders が stg_raw__orders を ref() で参照している場合、必ず stg_raw__orders が先に実行されます。

Lineage Graph（リネージグラフ）

DAG を視覚的に表示したものです。dbt docs serve で閲覧できるドキュメントサイトの右下にあるアイコンから確認できます。

データの流れを source → staging → intermediate → mart と一目で追えるため、影響範囲の把握やデバッグに非常に便利です。

Snowflake 連携で知っておきたい用語

Warehouse / Database / Schema（Snowflake の3階層）

Snowflake はオブジェクトを 3つの階層 で管理しています。dbt を使う上でもこの構造の理解は欠かせません。

階層 説明 dbt との関係
Warehouse SQLを実行するコンピュートリソース（仮想ウェアハウス）。サイズやオートサスペンドの設定で課金が変わる。 profiles.yml の warehouse に指定。dbt の処理中だけ起動するのがコスト最適化のコツ。
Database テーブルやビューを格納する論理的なコンテナ。 profiles.yml の database に指定。環境ごと（dev / prod）に分けることが多い。
Schema Database 内の名前空間。テーブルやビューはスキーマの中に作られる。 profiles.yml の schema に指定。dbt のカスタムスキーマ機能でレイヤーごとにスキーマを分けることも可能。
Snowflake のオブジェクト階層
ANALYTICS (Database)
├── DEV (Schema)
│   ├── STG_RAW__ORDERS (View)
│   └── FCT_ORDERS (Table)
└── PROD (Schema)
    ├── STG_RAW__ORDERS (View)
    └── FCT_ORDERS (Table)

Role

Snowflake のアクセス制御の基本単位です。dbt 用には専用の Role（例: TRANSFORM_ROLE）を作成し、必要なデータベース・スキーマ・ウェアハウスへの権限を付与するのが一般的です。

-- dbt 用 Role の作成例
CREATE ROLE TRANSFORM_ROLE;
GRANT USAGE ON WAREHOUSE TRANSFORM_WH TO ROLE TRANSFORM_ROLE;
GRANT USAGE ON DATABASE ANALYTICS TO ROLE TRANSFORM_ROLE;
GRANT CREATE SCHEMA ON DATABASE ANALYTICS TO ROLE TRANSFORM_ROLE;

profiles.yml での接続設定

Snowflake に接続する際、profiles.yml に設定する主なパラメータをまとめます。

パラメータ 説明 例
type アダプタの種類 snowflake
account Snowflake のアカウント識別子 xy12345.ap-northeast-1.aws
user ログインユーザー名 DBT_USER
password パスワード（環境変数推奨） {{ env_var('DBT_PASSWORD') }}
warehouse 使用する仮想ウェアハウス TRANSFORM_WH
database ターゲットデータベース ANALYTICS
schema デフォルトスキーマ DEV
role 使用する Role TRANSFORM_ROLE
threads 並列実行数 4

Transient Table

Snowflake の Transient Table は、通常のテーブルと異なり Fail-safe 期間（7日間のデータ保護）が無いテーブルです。Time Travel の保持期間も最大1日に制限されます。

dbt では Materialization を table にしたモデルの設定に transient: true を追加することで、Transient Table として作成できます。ストレージコストを抑えたい中間テーブルなどに有効です。

dbt_project.yml
models:
  my_project:
    staging:
      +materialized: view
    marts:
      +materialized: table
      +transient: false  # mart は通常テーブル
    intermediate:
      +materialized: table
      +transient: true   # 中間テーブルはTransientでコスト削減

よく使う dbt コマンド一覧

コマンド 説明
dbt debug 接続設定（profiles.yml）や環境が正しいかを検証する。初回セットアップ時にまず実行。
dbt deps packages.yml に記述したパッケージをインストールする。
dbt seed seeds/ ディレクトリの CSV ファイルをテーブルとして取り込む。
dbt run Model を実行し、Snowflake 上にテーブル/ビューを作成する。
dbt test Generic Test と Singular Test を実行する。
dbt build dbt run + dbt test + dbt seed + dbt snapshot を依存順にまとめて実行する。日常的にはこれが一番よく使う。
dbt compile Jinja テンプレートを展開した生の SQL を出力する（実行はしない）。デバッグに便利。
dbt docs generate ドキュメントサイト用の JSON ファイルを生成する。
dbt docs serve ドキュメントサイトをローカルで起動する。

ノードセレクタ（--select / --exclude）

特定のモデルだけを実行・テストしたい場合は --select（-s）オプションを使います。

# 特定のモデルだけ実行
dbt run --select fct_orders

# staging レイヤー全体を実行
dbt run --select staging.*

# fct_orders とその上流モデルをすべて実行（+ は上流を意味する）
dbt run --select +fct_orders

# fct_orders とその下流モデルをすべて実行
dbt run --select fct_orders+

おわりに

以上が、dbt × Snowflake プロジェクトを始めるにあたって押さえておきたい基本用語です。

最初は量が多く感じるかもしれませんが、実際にプロジェクトを作って dbt run → dbt test → dbt docs serve のサイクルを回してみると、自然と体に馴染んできます。

学習リソース

7
7
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
7
7

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?