motherduck-model-data

MotherDuck のデータモデリング

基本動作

複数モデルを扱う場合は、変換処理をレビュー可能な SQL ファイルにまとめ、プロジェクトで既に使われている dbt、SQLMesh、またはローカルの規約に従います。既存の規約がない場合は、ステージ別のディレクトリを使い、依存関係、マテリアライゼーション、ターゲットデータベースを記録した model_manifest.yml を用意します。単一テーブルのリクエストでは、指定された SQL または変更だけで十分です。

前提条件

既知のソーススキーマと接続を使用します。型、粒度、結合キーが不明な場合は、実装前に確認します。計画の作成には、ライブ接続がなくても、提示されたスキーマを使用できます。

デフォルトの方針

• トランザクション処理での書き込みではなく、分析クエリでの読み取りを想定して設計します。
• 高度に正規化された OLTP 形式のスキーマより、幅広く非正規化されたテーブルや、事前集計済みのサービングテーブルを優先します。
• 完全修飾名を使用し、テーブルとカラムにコメントを追加します。Guide が意図したカタログオブジェクトを確実に参照できるよう、オブジェクト名は安定したものにします。
• NOT NULL を積極的に使用します。主キーや外部キーが強制されるとは想定しないでください。
• 既存の dbt、SQLMesh、またはリポジトリ内のモデリング規約がある場合は、それを再利用します。軽量なひな形を作成するのは、プロジェクトで確立された構成がない場合に限ります。
• プロジェクトが単純でない場合は、raw、staging、analytics のライフサイクルステージを分けます。

ワークフロー

1. 新しいモデルを設計する前に、現在のソーステーブルと実際のカラム型を確認します。
2. モデル化する各テーブルのターゲットとなるライフサイクルステージと粒度を選びます。モデル間の依存関係を整理します。
3. 既存のプロジェクトに SQL を配置するか、新しい複数モデルのプロジェクトではひな形を参照します。
4. 各モデルを単独で実行できる SQL ファイルとして作成します。明示的な型、NULL 許容性、コメント、完全修飾名を使用します。鮮度とコストに基づいて、テーブル、CTAS による再構築、ビューのいずれを使うか決定します。
5. 依存関係とマテリアライゼーションは、プロジェクトのフレームワークか軽量なマニフェストのどちらか一方に記録します。両方には記録しません。
6. 実装時は、対象範囲のモデルを実行し、粒度と行数を検証します。MCP の DDL と CTAS には query_rw が必要です。回答、レビュー、計画の場合は、依頼がない限り、プロジェクトの作成やウェアハウスの変更は行わず、求められた説明または SQL を返します。

参考資料

現在のタスクに必要な参考資料のセクションだけを読みます。

• スキーマパターン、データ型の指針、CTAS とビューの使い分け、複合型、制約、プロジェクトのひな形の規約、よくあるモデリングの誤りについては、references/MODELING_PLAYBOOK.md を読みます。

関連スキル

不足している機能を補う場合に限り、関連スキルを読み込みます。確立済みのコンテキストは再利用します。

• 型の構文と関数の詳細には motherduck-duckdb-sql
• DDL、再構築、検証クエリの実行には motherduck-query
• 再モデリング前のソーススキーマの把握には motherduck-explore
• モデル化されたテーブルにデータを取り込む方法には motherduck-load-data
• 変換コードに含めるべきではない、永続的なビジネス定義や結合ルールには motherduck-manage-guides