Open10

【dbt】命名規則

dbt
YuichiYuichi

日付型のカラムに対して、データ型に応じて末尾の命名を変えることで、一貫性を持たせながら直感的に理解しやすくするアイデアを考えました。

アイデア

データ型 末尾の候補 説明 例
DATE _date _ymd 年月日（YYYY-MM-DD）を表す created_date, event_ymd
DATETIME _datetime _ts 日時（YYYY-MM-DD HH:MI:SS）を表す updated_datetime, log_ts
TIMESTAMP _ts _timestamp タイムゾーン付きの日時を表す ingested_ts, created_timestamp
TIME _time _hm 時刻（HH:MI:SS）を表す start_time, alarm_hm
YEAR _year 年のみを表す fiscal_year, published_year
MONTH _month _ym 年月（YYYY-MM）を表す sales_month, billing_ym

ポイント

  1. 視認性を重視
    • date / datetime / timestamp を明示的にすることで、型の違いがすぐにわかる。
    • ymd（年月日）や ym（年月）などの省略形を使うとコンパクトになる。
  2. SQL関数との一貫性
    • DATE() や TIMESTAMP() 関数と対応するように _date や _timestamp を使用。
    • CURRENT_TIMESTAMP() に対応して _ts という略称も有力。
  3. システム間の互換性
    • BIツールやデータ連携時のカラム識別がしやすくなる。
    • データウェアハウス（BigQueryなど）やアプリ側の仕様に合わせて _date / _ts などを使い分ける。
YuichiYuichi

raw_ → データレイク（未加工データ）
stg_ → ステージング（加工済みデータ）
int_ → 中間データ（ロジック適用後のデータ）
mrt_ → マート（最終分析用データ）

1. シンプルなレイヤー名

役割が短い接頭辞で明確に区別できる命名規則。

  • raw_* → データレイク（未加工データ）
    例: raw_sales, raw_logs
  • stage_* → ステージング（加工・整形データ）
    例: stage_customers, stage_orders
  • transform_* → 中間データ（ビジネスロジック適用後のデータ）
    例: transform_metrics, transform_finance
  • final_* → マート（完成形データ）
    例: final_kpis, final_entities

2. カラーモデル命名

レイヤーを「ブロンズ→シルバー→ゴールド」のように色で表現する方法。

  • bronze_* → データレイク
    例: bronze_transactions, bronze_events
  • silver_* → ステージング
    例: silver_customers, silver_sessions
  • gold_* → 中間データまたはマート
    例: gold_financials, gold_marketing_kpis
  • platinum_* → 最終マート（特に重要な分析用データ）
    例: platinum_insights, platinum_strategic_kpis

3. アクションベース命名

データのライフサイクルに基づき、動詞を用いた接頭辞を付ける方法。

  • ingest_* → データレイク（取り込み段階）
    例: ingest_logs, ingest_raw_data
  • clean_* → ステージング（データ整形）
    例: clean_orders, clean_events
  • prepare_* → 中間データ（準備段階）
    例: prepare_metrics, prepare_entities
  • deliver_* → マート（最終データ配信）
    例: deliver_kpis, deliver_dashboard_data

4. レイヤー番号命名

レイヤーの順序を数値で示し、データフローのステップを明示する方法。

  • l1_* → データレイク（Layer 1: Raw Data）
    例: l1_raw_events, l1_raw_logs
  • l2_* → ステージング（Layer 2: Cleaned Data）
    例: l2_stage_customers, l2_stage_transactions
  • l3_* → 中間データ（Layer 3: Transformed Data）
    例: l3_enriched_kpis, l3_prepared_finance
  • l4_* → マート（Layer 4: Final Data）
    例: l4_mart_kpis, l4_dashboard_ready

5. 業務・目的別命名

データの用途や最終消費者に合わせて役割を明確化。

  • raw_* → データレイク
    例: raw_finance, raw_marketing
  • base_* → ステージング（基本構築データ）
    例: base_customers, base_products
  • logic_* → 中間データ（ロジック適用済み）
    例: logic_sales, logic_operations
  • output_* → マート（最終出力データ）
    例: output_kpis, output_analysis

6. 日本語ベースの命名

日本語チーム向けに親しみやすく、業務フローを意識した命名規則。

  • raw_データ → データレイク
    例: raw_売上, raw_ログ
  • 整形_データ → ステージング
    例: 整形_顧客, 整形_注文
  • 加工_データ → 中間データ
    例: 加工_指標, 加工_在庫
  • 分析_データ → マート
    例: 分析_収益, 分析_KPI

7. その他のカスタム案

用途や好みに応じた独自の接頭辞を検討する方法。

  • lake_* → データレイク
  • refine_* → ステージング
  • model_* → 中間データ
  • serve_* → マート

例:

  • lake_sessions, refine_sales, model_revenue, serve_kpis

提案まとめ

以下のいずれかを選ぶことで、わかりやすく管理しやすい命名規則になります。

  1. カラーモデル（bronze_, silver_, gold_） → 直感的で広く使われている。
  2. レイヤー番号（l1_, l2_, l3_, l4_） → 明確なフローの順序。
  3. アクションベース（ingest_, clean_, prepare_, deliver_） → データ処理の意図がわかりやすい。

特定の命名規則がチームに合うか、好みを考慮して選んでください。

YuichiYuichi

https://zenn.dev/kyami/articles/4438f4d64185b4

Stagingレイヤー

  • 基本Stagingレイヤーでの集計や結合は非推奨、カラムのリネーム、型変換、基本的な計算は推奨
  • ファイル名に取得元情報を記載しよう
  • ソースデータ単位でサブティレクリを切りましょう（ビジネスグループごとに切るにはNG）
  • テーブルタイプはビューを推奨

Intermediateレイヤー

  • 中間層からはビジネス上の関心毎にサブディレクトリを切る
  • モデル名に処理の動詞を入れ込もう
  • 中間層はエンドユーザに見せない
  • 中間層はエフェメラルテーブルを推奨
  • 複雑な処理は分離するようにしましょう

Martsレイヤー

  • 部門別にサブディレクトリを切る
  • エンティティ毎に名前をつける
  • テーブルはインクリメンタルモデル
  • セマンティックレイヤーを採用しな場合、非正規化を推奨
  • 結合が多すぎるモデルは非推奨

その他の推奨事項

  • DRYの原則で同じ処理はマクロ化しましょう
  • テストは積極的にやりましょう
  • seed機能はあくまでウェアハウス内のデータを操作することを主軸である。ローディングツールにあらず
YuichiYuichi

Intermediate レイヤーの命名規則について、以下のようなルールを推奨します。

📁 ディレクトリ構造 

models/intermediate
└── [ビジネスドメイン]/
    ├── _int_[domain]__models.yml
    ├── int_[entity]s_[verb].sql
  • ビジネスドメインごとにサブディレクトリを分割（finance, marketing, sales, hr など）
  • モデル定義ファイル（_int_[domain]__models.yml）を用意

📌 命名規則

ファイル名 

int_[エンティティ]s_[動詞].sql
  • int_：Intermediate レイヤーであることを明示
  • [エンティティ]s：データの対象（複数形）
  • [動詞]：どのような変換をしているか

📝 動詞の例

動詞 意味・用途
pivoted 縦持ち → 横持ち変換
aggregated_to_[対象] 集計（例: aggregated_to_user）
joined 他のテーブルとの結合
fanned_out_by_[属性] 属性ごとに展開（例: fanned_out_by_quantity）
filtered フィルタ適用
windowed ウィンドウ関数適用
enriched_with_[追加情報] 他の情報を付与
scored スコアリング処理
funnel_created ファネル分析用データ作成
segmented_by_[属性] セグメント化（例: segmented_by_age）

📌 命名例

ファイル名 説明
int_payments_pivoted_to_orders.sql 支払いデータを注文単位にピボット
int_users_aggregated_to_region.sql ユーザーデータを地域ごとに集約
int_sessions_funnel_created.sql セッションデータをファネル分析用に変換
int_transactions_enriched_with_discounts.sql 取引データに割引情報を付与

このルールに従うことで、Intermediate レイヤーの構造が整理され、チームでの認識統一がしやすくなります。

YuichiYuichi

https://dev.classmethod.jp/articles/dbt-styling-dbt-models-best-practices/

  • 日付のみ：_date
  • 日次（timestamp,datetime）: _at

自分のルール

命名例（規則） 型 タイムゾーン 備考・用途
<event>_at TIMESTAMP UTC システム時刻やロギング、イベント発生時刻など
<event>_at_jst DATETIMEorTIMESTAMP JST JST など明示的なタイムゾーンを表したいときに使用
<event>_datetime DATETIME JST タイムゾーンを持たないが、JSTなどアプリ基準のローカル時間として扱いたいとき。表示・入力に使いやすい
<event>_date DATE JST 日付のみ必要な場合。予約日や記念日、誕生日など
  • ブール値(boolean)にはis_
  • customersテーブルのキーはcustomer_idという名前にすべき
  • イベントに関する列名は「過去形」表記にすべきです。
    例)
    created(作成された)
    updated(更新された)
    deleted(削除された)
    • enum の定義によく使われる type に統一すると、テーブル設計やコードが一貫しやすい。
      • ✅ 基本的には <属性名>_type を採用
      • ✅ 分類を明確に示す場合のみ <属性名>_category を使用

もし迷ったら、type に統一しておけば問題になることは少ないです。

YuichiYuichi

enum の定義によく使われる type に統一すると、テーブル設計やコードが一貫しやすい。
✅ 基本的には <属性名>_type を採用
✅ 分類を明確に示す場合のみ <属性名>_category を使用

カテゴリ管理の適切なレイヤー

カテゴリデータは、データ基盤内で主に以下のレイヤーで管理されることが一般的です：

  • データ利用レイヤー
    データ利用レイヤー（またはデータ利活用レイヤー）は、データを提供する層であり、カテゴリ情報を含むデータを抽出・変換・提供する役割を担います。この層では、REST APIやクエリエンジンを使用して、カテゴリ情報を外部システムに提供することが可能です15。
  • セマンティックレイヤー
    セマンティックレイヤーは、データの意味的な構造を定義し、ユーザーが理解しやすい形でデータを提供する役割があります。カテゴリ情報をこの層で管理すると、ビジネスユーザーが直接利用可能な形で提供できます8。

日本語化のタイミング

日本語化は、以下の観点から実施すべきです：

  1. セマンティックレイヤーでの日本語化
    セマンティックレイヤーでは、カテゴリ名や属性名などをビジネスユーザー向けに翻訳し、日本語化することで理解しやすい形にします。これにより、生成AIやBIツールなどの利用時に直感的な操作が可能となります
  2. データ利用レイヤーでの日本語化
    データ利用レイヤーでは、外部システムへのデータ提供時に日本語化されたカテゴリ情報を含めることで、エンドユーザーに分かりやすい情報を提供できます。特にAPIやクエリエンジンを通じたデータ提供時には、日本語化された情報が役立ちます

注意点

  • 日本語化はデータ変換プロセス（ETL）内で行うことも可能ですが、この場合はセマンティックレイヤーまたはデータ利用レイヤーで最終的な確認と調整が必要です。
  • 日本語化されたカテゴリ名は、一貫性と正確性を保つためにガバナンスプロセスで管理されるべきです
    これらのポイントを踏まえ、カテゴリ管理と日本語化の実施場所を選定してください。
YuichiYuichi

https://zenn.dev/ubie_dev/articles/d97c5ece4660bd

# 命名規則

## BigQueryとdbtモデルの命名の対応関係
- BigQueryテーブル: `<project_id>.<dataset_id>.<table_id>`
- dbtモデル名: ...
- dbtモデルディレクトリ: ...

## レイヤー別の命名規則
- Interface層(IF層):
  - データセット: `if_` + ソースデータセット名
  - テーブル: ソース名と完全一致 ...
- Data Component層(DC層):
  - データセット: `dc_` + ドメイン名
  - テーブル: ディメンションは`dim_`、ファクトは`fact_` ....
- Data Ware House層(DWH層):
  - データセット: `dwh_` + ドメイン名
  - テーブル: データの内容を反映した説明的な名前 ....
- Datamart層(DM層):
  - データセット: `dm_` + ドメイン名
  - テーブル: 分析や可視化の目的を示す説明的な名前 ....
YuichiYuichi

https://speakerdeck.com/tanakarian/data-warehouse-logic-design-by-using-dbt

資料まとめ：dbtを活用したデータ基盤の論理・物理設計の変遷

本資料は、Ubie株式会社におけるデータ分析基盤が、dbtの導入を経てどのように設計を改善してきたか、その過程と現在の設計思想（v2）をまとめたものです。

1. 背景と課題の変遷

初期（v0）：Airflow + SQL時代

  • 構成: Airflowから長大なSQLを実行し、ソースデータから直接データマートを作成。
  • 課題:
    • 低・再利用性: 「似たような処理だが少し違う」マートが乱立。
    • テストの困難さ: SQLが長大すぎて、品質テストの条件抽出が困難。

中期（v1）：dbt導入と三層構造

  • 構成: dbtを採用し、ステージング・DWH・マートの三層構造を導入。
  • 課題:
    • 責務の混在: 汎用的な共通処理（JST変換等）とドメイン固有のロジックが1つのSQLに混在。
    • 実装場所の迷い: 「DWHとマートのどちらに書くべきか」の判断基準が曖昧に。

2. 現在の論理設計（v2）

加工処理の責務を明確化するため、以下の4層構造で設計されています。

① Interface層（分析向け基本データ）

  • 役割: 最低限のケアを施した、特定のモデルに依存しない共通処理。
  • 主な処理: タイムスタンプのJST変換、カラム名変換、重複・不正値の排除。
  • 目的: 分析者が「細かいことを気にせず使えるログ」の提供。

② Component層（再利用可能なパーツ）

  • 役割: 特定のドメイン（例：問診、医療機関検索）のイベントを表現する層。
  • 要素:
    • Conformed Dimension: 基盤内で互換性のあるマスタデータ（例：医療機関リスト）。
    • Conformed Fact: ドメイン固有のイベントレコード。
  • 目的: 複数のDWHから参照される部品としての再利用性確保。

③ DWH層（分析のベーステーブル）

  • 役割: Componentを結合し、あるドメインの分析に必要な情報を集約。
  • 特徴:
    • 可視化（BI）の都合は意識せず、あくまでドメイン知識を整理。
    • ドメインに詳しくないアナリストでも、dbt docsを見れば使える状態を目指す。

④ DataMart層（特定の用途・可視化）

  • 役割: 特定の分析やBIツールでの利用を前提とした層。
  • 特徴:
    • BIツール（Tableau等）での使いやすさを優先。
    • Metrics Mart: 基本的なKPIを集計済み状態で保持し、数値の一貫性を担保。

3. 物理設計とテスト戦略

物理設計（BigQuery上）

各層ごとにデータセット名を命名規則で管理しています。

  • if_ (Interface): View
  • dc_ (Component): View
  • dwh_ (DWH): Table (IntermediateはView)
  • dm_ (DataMart): Table

テストの責務

  • 完全性 (Integrity): 主にComponent層で実施（nullチェック、unique、リレーション）。
  • 一貫性 (Consistency): 主にDataMart層で実施（レポート間での指標の整合性）。
  • 鮮度 (Freshness): 主にInterface層で実施（データの遅延検知）。

4. まとめと今後の展望

  • 導入のメリット: 各層の責務が明確になったことで、テストが書きやすくなり、高品質なデータの提供が可能になった。
  • 現在の課題: 依然としてモデリング（特にComponent層とDWH層の境界）には、事業理解とデータエンジニアリング双方の高度な知識が必要。

出典：Sotaro Tanaka (@sotaron) 「dbtを活用したデータ基盤の 論理・物理設計の現在地と振り返り」

YuichiYuichi

https://getdbt.slack.com/archives/C02NYJCRE80/p1701915986637529
https://web.archive.org/web/20131226082402/http://www.kimballgroup.com/1998/04/02/is-data-staging-relational/

1. 抱えている課題

  • 用語の重複: 「ステージング環境のステージングモデル」といった表現になり、混乱を招く。
  • 認知度の差: ソフトウェア開発における「STG環境」という言葉の方が一般的であるため、データエンジニアリング以外のエンジニアとのコミュニケーションに齟齬が出やすい。

2. 各氏が採用している代替案（命名）

公式の stg_ という接頭辞を避け、以下のような名称を採用している例が挙げられました。

  • lake / raw: 生データに近いニュアンスを強調。
  • gateway (prefix: gate_): 生データからの中継地点・入り口という意味。
  • source, cleansing, flatten, provisioning: 処理の内容（クレンジングやフラット化など）をそのまま名前にする。
  • interface, immediate: 中間層としての役割を強調。

3. なぜdbtは「staging」という言葉を選んだのか（考察）

  • データウェアハウスの伝統: 1990年代（キンボール氏の提唱など）から、データ加工プロセスの最初の置き場を「Staging Area」と呼ぶ文化があった。
  • プラットフォームの影響: SnowflakeなどのクラウドDWにおいて、ファイル置き場を「stage」と呼ぶ仕様と親和性が高い。
  • 文化の衝突: dbtが「ソフトウェア開発のベストプラクティス」をデータ界に持ち込んだ際、古くからあるデータ用語（Staging Area）と、ソフトウェア用語（Staging環境）が衝突してしまったのではないか。

4. 運用の現状

  • 公式ドキュメントに従い、違和感を覚えつつも stg_ を使っているケースが多い（後の担当者が混乱しないため）。
  • 独自レイヤー（raw -> staging -> analytics）を定義して運用している組織もあるが、dbtの標準を知っているメンバーからツッコミが入るなど、標準と独自のバランスに苦労している様子が見て取れます。