wren-generate-mdl

Wren MDL を生成 — CLI エージェントのワークフロー

バージョンの確認

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json をサイレントに取得します。 wren-generate-mdl キーの値を、このスキルのバージョン（上記のフロントマターに記載）と比較します。 リモートのバージョンのほうが新しい場合は、続行する前にユーザーに通知します。

wren-generate-mdl スキルの新しいバージョンが利用できます。 次のコマンドで更新してください。

npx skills add Canner/WrenAI --skill wren-generate-mdl

CLI はインストール済みのエージェントを自動検出します。特定のものを指定するには、--agent <name>（例：claude-code、cursor、windsurf、cline）を追加してください。

更新状況にかかわらず、以下のワークフローを続行します。

---

データベースのスキーマを検出し、Wren の YAML プロジェクト形式に変換して MDL プロジェクトを構築します。エージェントは、スキーマのイントロスペクションに環境内で利用できるデータベースツールを使用し、wren CLI が型の正規化、検証、ビルドを処理します。

セットアップ後のメモリとクエリのワークフローについては、wren-usage スキルを参照してください。

---

前提条件

• wren CLI がインストールされている（pip install "wrenai[<datasource>]"）
• 動作するデータベース接続がある（エージェントが認証情報を利用できる）
• wren プロファイルが設定済み（wren profile add）、または接続情報をすぐに利用できる

---

フェーズ 0 — 既存プロジェクトを検出する

目標： 現在のディレクトリがすでに wren プロジェクト内にある場合、どのように進めるかをユーザーに選んでもらいます。

現在の作業ディレクトリ（またはリポジトリルートまでの親ディレクトリ）に wren_project.yml が存在するか確認します。見つかった場合：

1. 既存の wren プロジェクトが検出されたことをユーザーに伝え、そのパスを示します。
2. 次の選択肢を提示します。
   • リセット — 既存のプロジェクト（models/、views/、 relationships.yml、instructions.md）を消去し、同じディレクトリに wren_project.yml を再構築して、最初から生成します。
   • 新しいパス — 既存のプロジェクトには手を加えず、新しいプロジェクト用に 別のディレクトリを選択します。ユーザーに新しいパスを尋ねてから、 wren context init --path <new_path> を実行し、フェーズ 1 からそのパスを 使用して続行します。

既存のプロジェクトが検出されなかった場合は、フェーズ 1 に進みます。

---

フェーズ 1 — 接続と対象範囲を確定する

目標： エージェントがデータベースに接続できることを確認し、ユーザーと対象範囲について合意します。

1. 利用可能なツールを使って接続を確認します。

   • SQLAlchemy の場合：engine.connect() でテストします
   • データベースドライバーの場合：SELECT 1 のような簡単なクエリを実行します
   • wren プロファイルがある場合：wren profile debug で設定を確認します
   • wren 経由で生の SQL を実行する場合：wren --sql "SELECT 1"（プロファイルまたは接続ファイルが必要）

2. ユーザーに次の点を尋ねます。

   • 含める スキーマ または データセット（1 つしかない場合は省略）
   • すべてのテーブルを含めるか、一部に絞るか
   • wren の データソースの種類（例：postgres（Aurora を含む）、mysql（Aurora を含む）、bigquery、snowflake）— 型の正規化に使う方言の指定に必要です

---

フェーズ 2 — スキーマを検出する

目標： テーブル名、カラム名、カラムの型、制約を収集します。

利用可能なイントロスペクション方法を使用します。一般的な方法を、利便性の高い順に示します。

オプション A：SQLAlchemy（利用可能な場合に推奨）

from sqlalchemy import create_engine, inspect

engine = create_engine(connection_url)
inspector = inspect(engine)

tables = inspector.get_table_names(schema="public")

for table in tables:
    columns = inspector.get_columns(table, schema="public")
    # columns → [{"name": "id", "type": INTEGER(), "nullable": False, ...}]

    pk = inspector.get_pk_constraint(table, schema="public")
    # pk → {"constrained_columns": ["id"], "name": "orders_pkey"}

    fks = inspector.get_foreign_keys(table, schema="public")
    # fks → [{"constrained_columns": ["customer_id"],
    #          "referred_table": "customers",
    #          "referred_columns": ["id"]}]

オプション B：データベース固有のドライバー

• psycopg / asyncpg（Postgres）： information_schema.columns と information_schema.table_constraints をクエリします
• google-cloud-bigquery： client.list_tables()、client.get_table() → table.schema
• snowflake-connector-python： SHOW COLUMNS IN TABLE、SHOW PRIMARY KEYS IN TABLE
• clickhouse-driver： DESCRIBE TABLE、system.tables

オプション C：wren 経由で生の SQL を実行する

ドライバーを利用できないものの、wren プロファイルが設定済みの場合は、 wren 自体を介して information_schema にクエリを実行します。

wren --sql "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'" -o json
wren --sql "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'orders'" -o json

注：これは MDL レイヤーを経由するため、最小限の MDL がすでにある場合、またはデータベースが information_schema を通常のテーブルとしてサポートしている場合にのみ動作します。何もない状態からの初期構築には、オプション A または B を推奨します。

---

フェーズ 3 — 型を正規化する

目標： 生のデータベース型を wren-core 互換の型に変換します。

Python のインポート（バッチ処理に推奨）

from wren.type_mapping import parse_type, parse_types

# Single type
normalized = parse_type("character varying(255)", "postgres")  # → "VARCHAR(255)"

# Batch — entire table at once
columns = [
    {"column": "id", "raw_type": "int8"},
    {"column": "name", "raw_type": "character varying"},
    {"column": "total", "raw_type": "numeric(10,2)"},
]
normalized_cols = parse_types(columns, dialect="postgres")
# Each dict now has a "type" key with the normalized value

CLI（Python のインポートが利用できない場合）

単一の型：

wren utils parse-type --type "character varying(255)" --dialect postgres
# → VARCHAR(255)

バッチ（標準入力の JSON）：

echo '[{"column":"id","raw_type":"int8"},{"column":"name","raw_type":"character varying"}]' \
  | wren utils parse-types --dialect postgres

---

フェーズ 4 — MDL プロジェクトをスキャフォールディングして作成する

目標： YAML プロジェクトの構造を作成します。

ステップ 1 — プロジェクトを初期化する

wren context init --path /path/to/project

これにより、次が作成されます：

project/
├── wren_project.yml
├── models/              # business-facing tables/models
├── views/               # named SQL statements
├── cubes/               # pre-aggregation cubes (measures + dimensions)
├── relationships.yml
└── instructions.md

キューブを定義するタイミング： ユーザーが「月別の売上」や「上位の顧客」のような集計に関する質問をする場合は、モデルと併せてキューブを定義してください。 キューブを使うと、エージェントは GROUP BY や DATE_TRUNC の SQL を手書きせずに、構造化されたクエリー API を利用できます。キューブガイドを参照してください。

重要：wren_project.yml の catalog と schema

これらは Wren Engine の内部名前空間であり、データベース固有のカタログやスキーマではありません。複数プロジェクトの名前空間を意図的に設定する場合を除き、デフォルト（catalog: wren、schema: public）を維持してください。

実際のデータベースのカタログ／スキーマは、モデルごとに table_reference で指定します（ステップ 2 を参照）。データベースのカタログ／スキーマの値を wren_project.yml にコピーしないでください。

ステップ 2 — モデルファイルを作成する

各テーブルについて、models/ の下に YAML ファイルを作成します。snake_case の命名を使用してください（ビルド時に自動的に camelCase に変換されます）。

# models/orders/metadata.yml
name: orders
table_reference:
  catalog: ""           # database catalog (empty string if not applicable;
                        #   for DuckDB, use the DB file name without extension,
                        #   e.g. jaffle_shop.duckdb → catalog: jaffle_shop)
  schema: public        # database schema (this IS the DB schema)
  table: orders         # database table name
primary_key: order_id
columns:
  - name: order_id
    type: INTEGER
    not_null: true
  - name: customer_id
    type: INTEGER
  - name: total
    type: "DECIMAL(10, 2)"
  - name: status
    type: VARCHAR
    properties:
      description: "Order status: pending, shipped, delivered, cancelled"

ステップ 3 — リレーションシップを作成する

フェーズ 2 で検出した外部キー制約に基づいて作成します：

# relationships.yml
- name: orders_customers
  models:
    - orders
    - customers
  join_type: many_to_one
  condition: "orders.customer_id = customers.customer_id"

結合タイプの対応：

• 外部キー側のテーブル → 主キー側のテーブル：many_to_one
• 主キー側のテーブル → 外部キー側のテーブル：one_to_many
• 一意の外部キー：one_to_one
• 中間テーブル：many_to_many

外部キーが見つからない場合は、命名規則から推測します：

• 列名が <table>_id または <table_singular>_id → <table> への外部キーである可能性が高いです
• 推測したリレーションシップについて、ユーザーに確認を求めてください

ステップ 4 — 説明を追加する（任意ですが有用です）

ユーザーに次の説明を求めます：

• 各モデル（テーブルが表すものについての 1～2 文）
• 主要な列（特に計算フィールドや、名前から意味が明らかでない列）

これらの説明は wren memory index によってインデックス化され、LLM のクエリー精度を大幅に向上させます。

---

フェーズ 5 — 検証してビルドする

# Validate YAML structure and integrity
wren context validate --path /path/to/project

# If strict mode is desired:
wren context validate --path /path/to/project --strict

# Build JSON manifest
wren context build --path /path/to/project

# Verify against database
wren --sql "SELECT * FROM <model_name> LIMIT 1"

検証に失敗した場合は、報告された問題を修正して再実行してください。よくあるエラー：

• モデル名／列名の重複
• 主キーがない
• 存在しないモデルを参照するリレーションシップ
• 無効な列型（parse_type を使って再実行してください）

---

フェーズ 6 — メモリを初期化する

# Index schema (generates seed NL-SQL examples automatically)
wren memory index

# Verify
wren memory status

このステップの後、wren memory fetch と wren memory recall が使用できるようになります。クエリーワークフローについては、wren-usage スキルを参照してください。

---

フェーズ 7 — ユーザーと反復する

初期の MDL は出発点です。次の方法で改善してください：

• ビジネスロジックに基づく計算列の追加
• よく使われるクエリーパターン向けのビューの追加
• 実際のクエリーの使用状況に基づく説明の改善
• 必要に応じたアクセス制御（RLAC/CLAC）の追加

各変更は次の手順で行います：YAML を編集 → wren context validate → wren context build → wren memory index。

---

クイックリファレンス

タスク	コマンド／方法
テーブルの検出	エージェント独自のツール（SQLAlchemy、ドライバー、生 SQL）
列と型の検出	エージェント独自のツール
制約の検出	エージェント独自のツール
型の正規化（Python）	from wren.type_mapping import parse_type
型の正規化（CLI）	wren utils parse-type --type T --dialect D
型の正規化（バッチ）	wren utils parse-types --dialect D < columns.json
プロジェクトのスキャフォールディング	wren context init
モデルの作成	models/<name>/metadata.yml を作成
リレーションシップの作成	relationships.yml を編集
検証	wren context validate
マニフェストのビルド	wren context build
クエリーのテスト	wren --sql "SELECT * FROM <model> LIMIT 1"
メモリのインデックス化	wren memory index

---

避けるべきこと

• MDL にデータベース固有の型文字列をハードコードしないでください。常に parse_type で正規化してください。
• ビルド前の検証を省略しないでください。無効な YAML は、エラーが通知されないまま壊れたマニフェストを生成します。
• 列の型を推測しないでください。実際のデータベースから調査してください。
• 結合条件を確認せずにリレーションシップを記述しないでください。条件を誤ると、クエリエラーが通知されないまま発生します。
• ビルド後に wren memory index を実行しないままにしないでください。古いインデックスは再現率を低下させます。