data-analytics-engineering

データ分析エンジニアリング

コードで定義するマート、API としてのメトリクス、重要なインターフェースのコントラクト、再利用性や AI／BI での利用を向上させる場合に限ったセマンティックレイヤー、そして人間とエージェントの双方にオーナー、リネージ、品質、ガバナンスを公開するメタデータシステム。

主な情報源：data/sources.json。確定的な推奨を提示する前に、時間とともに変化する主張は公式ドキュメントで最新情報を確認してください。

使用する場面

• 分析エンジニアリングスタック（dbt、SQLMesh、Coalesce）を選定または改善する
• マート、粒度、ディメンション、ファクト、ワイドテーブル、アクティビティスキーマを定義する
• セマンティックレイヤー（dbt Semantic Layer、Lightdash、Cube、ウェアハウスネイティブ）を設計または移行する
• データコントラクト、メトリクスガバナンス、オーナーシップ、カタログ、リネージを追加する
• データ品質チェック、鮮度の監視、異常検知、リリースゲートを構築する
• ダッシュボード、ノートブック、API、AI／NLQ 分析向けの BI 対応モデルを準備する

使用しない場面

• レイクハウスまたはデータ取り込みアーキテクチャ -> data-lake-platform
• プロダクト／イベントの計測、アトリビューション、または ID 解決 -> marketing-product-analytics
• OLTP のチューニング、インデックス、ロック、またはトランザクションデータベースの操作 -> data-sql-optimization
• Metabase API の自動化 -> data-metabase
• ML の特徴量エンジニアリング、実験、またはモデル評価 -> ai-ml-data-science

トリアージチェックリスト

推奨を行う前に、次の項目を確認してください。

• 正式なビジネスメトリクスは何ですか。また、それぞれのオーナーは誰ですか？
• 提供要件：ダッシュボード、ノートブック、API、組み込み分析、または AI／NLQ のどれですか？
• 変換処理のベースライン：dbt、SQLMesh、ビジュアルツール、またはウェアハウスの SQL のみのどれですか？
• どのデータセットがコントラクトを必要としますか（下流の利用者がスキーマ、鮮度、セマンティクスに依存していますか）？
• セマンティックレイヤーが必要ですか。それとも、現在は適切にガバナンスされたマートで十分ですか？
• カタログ、リネージ、オーナーシップ、アクセス、品質をすでにカバーしているメタデータシステムはどれですか？

スタックの参照先

これらのツールのリリース段階、アダプターの対応状況、ライセンス、企業の所有関係は、リリースや取引によって変わります。記憶に頼って述べず、判断に必要な情報を調べてください。このスキル内の他のファイルでは、ツールの状況を繰り返し記載せず、ここを参照しています。

推奨する前に確認する項目	調べる内容	主な情報源
dbt エンジンの変更（dbt Core または Fusion、ローカルまたはプラットフォーム）	ユーザーのウェアハウスとデプロイモードでのリリース段階およびアダプターごとの利用可否	dbt リリースノートと、対象バージョンの dbt アップグレードガイド
dbt Semantic Layer／MetricFlow	現在のセマンティック YAML 仕様、リリース、BI 連携	dbt Semantic Layer のドキュメント、PyPI の MetricFlow リリース履歴
SQLMesh	リリース、ライセンス、ガバナンス団体	SQLMesh リポジトリと、その財団プロジェクトのページ
ツール選定の理由としてのベンダーリスク	各候補の現在の所有者、ライセンス、ガバナンス団体	ベンダーのプレスページ、各プロジェクトのLICENSEファイルと財団のページ

• **エンジンのアップグレード：**本番環境への移行は、リリースノートでそのデプロイモードについて一般提供と記載されたアダプターに限ってください。それ以外のアダプターでは、現行エンジンと並行して新しいエンジンを CI で実行し、本番環境はそのまま維持してください。
• **ベンダーリスク：**分析ツールは統合が進んでいるため、独立しているように見える2つのツールが同じ所有者のもとにある場合があります。「ベンダーからの独立性」を選定理由にする前に確認してください。同じ所有者の場合は、所有者が変わっても何が維持されるかを比較します。実行するコードのライセンス、中立的な財団がプロジェクトを統治しているか、モデルコードの移植性（プレーンな SQL か、ベンダー固有のテンプレートや設定か）を確認してください。

デフォルトのワークフロー

1. まず指標の契約を確定する — KPI 名、ビジネスロジック、粒度、オーナー、ディメンションを assets/metric-dictionary.md で定義します
2. 変換の基準を1つ選ぶ — セマンティックレイヤーのツールについて議論する前に、dbt または SQLMesh のいずれかに標準化します（references/tool-comparison.md）
3. 利用を前提にモデリングする — staging -> intermediate -> marts のレイヤーを構築し、references/modeling-patterns.md を参考に最終的な形（スター型、ワイド型、アクティビティスキーマ）を選びます
4. 重要なインターフェースに契約を追加する — スキーマ、オーナーシップ、鮮度、品質に関する期待値を適用します（references/contracts-catalogs-lineage.md）
5. 効果が得られる場合にのみセマンティックサービングを選ぶ — references/semantic-layer-patterns.md を使って、dbt ネイティブ、Lightdash、Cube、ウェアハウスネイティブのいずれかを判断します
6. リリースに安全な品質管理を追加する — 静的テスト、鮮度、監査、異常モニタリングを導入します（references/data-quality-testing.md と references/release-and-ci-patterns.md）
7. 発見しやすさとガバナンスを確保する — アセット、リネージ、オーナー、変更通知をカタログに登録します（references/metric-governance.md と assets/ownership-catalog-worksheet.md）

判断：変換の基準を選ぶ

What does your team care about most?
  Plan-based deployment, environment isolation, backfill control
    -> SQLMesh
  Broadest ecosystem, contracts, semantic layer, dbt-native CI
    -> dbt (dbt Core or the dbt platform)
  Visual metadata-driven development, enterprise onboarding speed
    -> Coalesce
  Already on dbt and want faster compile + typed SQL
    -> Evaluate dbt Fusion, only on adapters that are GA for your deployment mode (see Stack Lookups)

判断：セマンティックレイヤーを追加するか？

Are the same business metrics reimplemented in 3+ places?
  NO -> Governed marts only; revisit when the answer flips to YES
  YES ->
    Most consumers are dbt-native?
      YES -> dbt Semantic Layer (MetricFlow) or Lightdash
    Need embedded analytics or product-facing APIs?
      YES -> Cube
    Single warehouse platform?
      Snowflake -> Snowflake Semantic Views
      Databricks -> Unity Catalog Metric Views
    Consumers need a business-friendly metric catalog as much as a query layer?
      YES -> Lightdash (or semantic layer + OpenMetadata/DataHub catalog)

判断：リリース前に指標の変更を分類する

変更クラス	例	必須のリリース手順
追加	新しい指標、ディメンション、または任意フィールド	粒度とソースの網羅性を検証し、公開する前にオーナーと定義を公表します
修正	過去の値が変わるバグ修正	代表的な期間について旧ロジックと新ロジックを並行実行し、影響を受ける期間と利用者を定量化して、変更通知を発行します
破壊的	名前変更、削除、粒度の変更、または意味の再定義	指標またはフィールドにバージョンを付け、互換性を保つ期間を設け、利用者を特定して移行し、ロールバック方法を定義します

修正および破壊的変更では、照合時に合計と意図した粒度でのセグメント単位の結果を比較する必要があります。総計が一致していても、相殺されるエラー、ファンアウト、母集団の変化が隠れている可能性があります。オーナーが測定された差分を承認し、下流の利用者がすべて特定され、合意した期間中に旧定義を復元できる状態になるまで、切り替えないでください。

クイックリファレンス

タスク	リソース	読み込むタイミング
dbt、SQLMesh、Coalesce のどれを選ぶか	references/tool-comparison.md	新しいスタックの選定または移行
スタースキーマ、ワイドスキーマ、アクティビティスキーマのどれを選ぶか	references/modeling-patterns.md	データマートとセマンティック境界の設計
セマンティックレイヤーを追加するか判断する	references/semantic-layer-patterns.md	メトリクスの再利用、NLQ、API、BI 向けデータ提供
コントラクト、オーナーシップ、リネージ、カタログを追加する	references/contracts-catalogs-lineage.md	共有データマートとガバナンス対象データセット
テスト、監査、異常チェック、CI ゲートを追加する	references/data-quality-testing.md	リグレッションと古いデータを防ぐ
メトリクスのライフサイクルと廃止を定義する	references/metric-governance.md	経営指標と共有 KPI プログラム
ロールアウト、二重実行、バックフィルを計画する	references/release-and-ci-patterns.md	安全なデプロイと移行
PII の分離、ボールトパターン、仮名化	references/pii-vault-and-pseudonymisation.md	LLM／AI 向けのクエリインターフェース、または GDPR の対象範囲
メトリクス定義のドラフトを作成する	assets/metric-dictionary.md	新しい KPI またはメトリクスのリファクタリング
セマンティックレイヤー設計のドラフトを作成する	assets/semantic-layer-spec.md	データ提供レイヤーの設計レビュー
データ品質のカバレッジ案を作成する	assets/data-quality-test-plan.md	モデルごとのテスト計画
SQLMesh プロジェクトまたはモデルを開始する	assets/transformation/sqlmesh/template-sqlmesh-project.md、assets/transformation/sqlmesh/template-sqlmesh-model.md	SQLMesh のセットアップまたはモデル定義。以下の SQLMesh テンプレート一覧も参照してください
メトリクスの変更を周知する	assets/metric-change-notice.md	互換性を損なう、または損なわないメトリクスの更新
オーナーとカタログの項目を記録する	assets/ownership-catalog-worksheet.md	ガバナンスと検索性のセットアップ
セマンティックレイヤーへ移行する	assets/semantic-layer-migration-checklist.md	アドホック SQL からガバナンス対象のメトリクスへの移行
データ品質インシデントに対応する	assets/data-quality-incident-runbook.md	障害、古いデータ、またはコントラクト違反

CI/CD 品質ゲートのチェックリスト

dbt プロジェクト（PR チェック）：

dbt deps
dbt parse
# prod-artifacts/ holds the production manifest.json (or set DBT_ENGINE_STATE)
dbt build --select state:modified+ --defer --state ./prod-artifacts

• コントラクト対象モデルで障害が発生していない
• 重要なソースの鮮度チェックに合格している
• 経営 KPI の変更に対する比較クエリを実行している
• すべてのデータマートモデルでスキーマテストに合格している
• デプロイ後の異常監視で新たなアラートが発生していない

SQLMesh プロジェクト（PR／プレビューのチェック）：

sqlmesh plan --no-prompts dev
sqlmesh test
sqlmesh audit   # SQLMesh has no state: selector; audit specific models with --model <name> (repeatable)

• apply の前にプランの差分をレビューしている
• ユニットテストがローカルで合格している（ウェアハウスの計算リソースを消費しない）
• 変更したモデルの監査に合格している
• デプロイ前にフォワードオンリーまたはバックフィルの範囲を確認している

運用原則

1. メトリクスは API です — 安定した名前、明確なオーナー、バージョン管理された変更、明示的な廃止期間を設けます。KPI の意味を予告なく変更してはいけません。
2. 1 モデルにつき 1 つの粒度 — データマートの粒度は曖昧さのない 1 つのものにします。異なる粒度を混在させず、別のモデルを作成してください。
3. 共有インターフェースにコントラクトを設定する — 経営向けデータマート、引き渡しテーブル、多くのチームが利用するモデルには必須です。一時的なステージングモデルすべてにコントラクトを設定する必要はありません。
4. セマンティックレイヤーは任意です — 複数の利用者が、ガバナンスの行き届いた再利用、NLQ／AI アクセス、またはプロダクト品質のメトリクス API を必要とする場合に追加します。ガバナンスの行き届いたデータマートで十分な場合は不要です。
5. メタデータは人とエージェントのためのものです — 価値の高いアセットには、説明、オーナー、リネージ、品質ステータス、アクセス境界を必須とします。

よくあるアンチパターン

アンチパターン	根本原因	解決策
ダッシュボードやノートブックに KPI ロジックを記述する	ガバナンスが適用されたマートがない	まずマートまたはセマンティックモデルで定義する
1 つのマートに複数の粒度がある	ダッシュボードの利便性	粒度ごとに別々のモデルを作成する
すべてのステージングモデルにコントラクトを適用する	ガバナンスの誤った適用	共有される重要度の高いインターフェースにのみコントラクトを適用する
マートが安定する前にセマンティックレイヤーを導入する	抽象化が早すぎる	エンティティや指標を定義する前にマートを安定させる
あらゆるリクエストに同じ 360 テーブルを使う	モデリング規律の欠如	1 つのモデル、1 つの粒度、1 つの目的にする
ドキュメント化されていないマートへの AI／NLQ アクセスを許可する	メタデータの不足	AI アクセスの前に、粒度、所有者、鮮度のコントラクトを必須にする

既知の落とし穴

• 緩やかに変化するディメンションが KPI の結合に混入し、過去の数値を気づかないうちに変えてしまいます。
• 通知、所有者の承認、非推奨化期間なしに、指標のリファクタリングで意味が変わってしまいます。
• ID の統合、アトリビューション、セマンティック指標が、明示的な優先順位ルールなしに共存しています。
• セマンティックレイヤーがあれば、リリース管理、データテスト、変更の周知が不要になると思い込んでしまいます。
• ファンアウトによる重複：隠れた 1 対多の関係（例：顧客ごとに複数の住所がある、注文ごとに複数のアトリビューション接点がある）を持つディメンションにファクトを結合すると、加算可能な指標が気づかないうちに重複します。マートに追加した結合ごとに、最後だけでなく結合の前後で行数を確認してください。
• セマンティックレイヤーでの非加算指標：比率、ユニーク数、パーセンタイルは、ディメンション間で単純に合計しても集計できません。事前計算した比率を新しいディメンションでスライスできるセマンティックレイヤーでは、クエリ実行時に基礎となる要素から再計算するよう指標を定義しない限り、もっともらしく見えても誤った数値が生成されます。
• 有効期間を考慮しない SCD Type 2 結合：ファクトのイベント時点で有効だった行ではなく、ディメンションの現在の行をファクトテーブルに結合すると、ディメンション属性が変わるたびに過去のデータが書き換えられます。「今月は何も起きていないのに数値が変わった」という事態のよくある原因です。
• 冪等性のないバックフィル：置換ではなく追加する（または自然キーによる重複排除を行わない）バックフィルや再処理ジョブは、テストが最新パーティションだけを対象にしている場合、構造上の一意性テストでは検出できない二重計上をひそかに引き起こします。
• 鮮度 SLA におけるタイムゾーン／DST のずれ：現地時刻で定義された鮮度の時間枠は、年に 2 回、また UTC の日付境界付近で破綻します。鮮度のしきい値は UTC で定義し、カレンダー日単位の粒度はソースシステムのタイムスタンプによる偶然ではなく、モデリング上の判断として扱ってください。
• 集計 KPI におけるシンプソンのパラドックス：セグメントの構成比が変化すると、組織全体の指標がすべての基礎セグメントと逆方向に動くことがあります。KPI 全体の傾向に対してアラートを出す前に、セグメントレベルの傾向が実際に一致しているか確認してください。

スクリプト

スクリプト	目的
scripts/analytics_linter.py	指標辞書の JSON ファイルを検証、リントし、健全性スコアを算出する

# Validate required fields, duplicate names, and undefined data sources
python scripts/analytics_linter.py validate --input data/valid-metric-dictionary.json

# Lint metric quality: missing owners, undocumented dimensions, naming, SLAs
python scripts/analytics_linter.py lint --input data/valid-metric-dictionary.json

# Generate a Markdown metric dictionary health report
python scripts/analytics_linter.py report \
  --input data/sample-metric-dictionary.json \
  --output metric-health-report.md

データ

ファイル	説明
data/sources.json	このスキル用に厳選された参照ソース
data/valid-metric-dictionary.json	スモークテストとクイックスタート例に使用する、本番環境で有効な 15 指標の辞書
data/sample-metric-dictionary.json	リントのデモ用に意図的な欠落を含む、現実的な 15 指標の辞書

ナビゲーション

ファイル	読み込むタイミング
references/tool-comparison.md	dbt、SQLMesh、Coalesce、またはセマンティックレイヤーツールを選択・比較するとき
references/modeling-patterns.md	マートレイヤー、粒度、スター／ワイド／アクティビティスキーマを設計するとき
references/semantic-layer-patterns.md	セマンティックサービングレイヤーの採用を判断し、実装するとき
references/contracts-catalogs-lineage.md	共有アセットにデータコントラクト、カタログメタデータ、リネージを追加するとき
references/data-quality-testing.md	テストスイート、鮮度チェック、異常監視を構築するとき
references/metric-governance.md	共有 KPI を管理、バージョン管理、非推奨化するとき
references/release-and-ci-patterns.md	CI/CD パイプライン、デュアルラン検証、バックフィル、安全な切り替えを行うとき
references/pii-vault-and-pseudonymisation.md	LLM／AI または GDPR 対象のサーフェスで、PII を分析用ファクトから分離するとき
references/transformation-patterns.md	dbt または SQLMesh の変換レイヤーを設計するとき（data-lake-platform から移動）
references/lake-data-quality-patterns.md	レイクネイティブテーブルに GX／Soda の品質コントラクトを追加するとき（data-lake-platform から移動）

対象外： 因果推論、ネットワーク科学、情報理論、制約理論分析です。DAG の影響範囲を調べるには、リネージグラフ上で dbt ls -s model+ または len(nx.descendants(G, node)) を使用してください。パイプラインの遅延によるボトルネックには、foundations-theory-of-constraints を使用してください。分析データの因果帰属、相互情報量による特徴量選択、またはネットワーク分析には、foundations-causal-inference、foundations-information-theory、または foundations-network-science を使用してください。

テンプレート

• dbt：プロジェクトテンプレート
• SQLMesh のセットアップとモデリング：プロジェクト、モデル、インクリメンタル、DAG
• SQLMesh の検証と運用：テスト、本番環境、セキュリティ、レイヤー化とアクセス
• assets/metric-dictionary.md
• assets/semantic-layer-spec.md
• assets/data-quality-test-plan.md
• assets/metric-change-notice.md
• assets/ownership-catalog-worksheet.md
• assets/semantic-layer-migration-checklist.md
• assets/data-quality-incident-runbook.md

関連スキル

• data-lake-platform — 取り込み、テーブル形式、オーケストレーション、データメッシュ
• data-sql-optimization — トランザクション SQL のパフォーマンスと運用チューニング
• marketing-product-analytics — イベント計測と顧客獲得の測定
• data-metabase — Metabase の自動化とダッシュボードのスクリプト作成
• ai-ml-data-science — 実験とモデリングのワークフロー

最新情報に基づく方針

• ベンダーの機能、構文、料金、制限、リリースによって変わる推奨事項については、data/sources.json の trust_tier: primary の項目を優先してください。
• 推奨事項について質問された場合は、最新の公式ドキュメントと最近のリリースノートを確認してください。
• 検証済みの事実と判断を分け、戦略的な意見であることを明記してください。
• ウェブにアクセスできない場合は、推奨事項の一部は未検証であると伝えてください。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な過去の経緯を確認する場合、または利用可能な代替資料としてのみ、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

参照後、覚えておく価値のあるパターン、防ぐべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを learnings.md に1件追記してください。SKILL.md 自体は変更しないでください。