wren-usage

Wren Engine CLI — エージェントのワークフローガイド

バージョンの確認

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json を通知せずに取得します。 wren-usage キーと、このスキルのバージョン（上記のフロントマターから取得）を比較します。 リモートのバージョンのほうが新しい場合は、先にユーザーへ通知します。

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

npx skills add Canner/WrenAI --skill wren-usage

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

更新状況にかかわらず、以下のワークフローを続けてください。

---

事前確認 — 環境とインストールの確認

目的： ワークフローを開始する前に、wren CLI を使用できることを確認します。

ステップ 1 — Python 仮想環境の確認

python -c "import sys; print(sys.prefix)"（または同等のコマンド）を実行して、 仮想環境が有効かどうかを確認します。

• 仮想環境が有効でない場合は、ユーザーに警告し、次のどちらにするかを確認します：
  • 仮想環境を作成する（例：python -m venv .venv && source .venv/bin/activate）
  • 仮想環境を使わずに続行する（推奨されません。グローバルパッケージが汚染される可能性があります）

ステップ 2 — wren CLI がインストールされているか確認

wren --version を実行します。コマンドが見つからない場合、またはエラーが発生した場合：

1. wren CLI がインストールされていないことをユーザーに伝えます。

2. インストールを手伝うかどうかをユーザーに確認します。

3. ユーザーが同意した場合、インストールする データソースの追加機能 を特定します：

   プロジェクトから自動検出： 現在のディレクトリが Wren プロジェクト内にあるか確認します（リポジトリのルートまで wren_project.yml を探します）。 見つかった場合は、cat ~/.wren/profiles.yml でアクティブなプロファイルを読み取るか、 プロジェクトのプロファイル設定からデータソースのヒントを探します。そこから データソースの種類を特定します。

   ユーザーに確認： プロジェクトが検出されない場合、またはデータソースを 推定できない場合は、接続する予定のデータベースをユーザーに確認します。有効な 追加機能：postgres（Aurora Postgres 用）、mysql（Aurora MySQL 用）、bigquery、snowflake、clickhouse、 trino、mssql、databricks、redshift、spark、athena、oracle。 DuckDB はデフォルトで含まれているため、追加機能は不要です。

4. 特定または選択した追加機能を使ってインストールします：

   # DuckDB (no extra needed)
   pip install "wrenai"
   
   # Other datasources
   pip install "wrenai[<datasource>]"
   

   セマンティックメモリ、対話型プロンプト、Web UI も有効にするには（推奨）：

   pip install "wrenai[<datasource>,main]"
   # or for DuckDB:
   pip install "wrenai[main]"
   

5. 確認します：wren --version

wren --version が成功した場合は、以下の該当するワークフローに進みます。

---

wren CLI は、MDL（Model Definition Language）セマンティックレイヤーを介してデータベースにクエリを実行します。生のテーブルではなく、モデル名を使って SQL を記述します。エンジンは対象の方言に変換します。

すべてを動かすのは、次の 2 つです：

• プロファイル — データベース接続とデータソースの種類。wren profile で管理します（~/.wren/profiles.yml に保存されます）
• プロジェクト — YAML 形式の MDL モデル定義。wren context build で target/mdl.json にコンパイルされます

CLI はアクティブなプロファイルから接続情報とデータソースを読み取ります。アクティブなプロファイルを確認するには wren profile list を、切り替えるには wren profile switch <name> を使います。dry-plan は --datasource / -d も受け付けるため、プロファイルを使わずにトランスパイルのみを実行できます。

メモリに関する判断については、references/memory.md を参照してください。 SQL 構文、CTE ベースのモデリング、エラー診断については、references/wren-sql.md を参照してください。 プロジェクト構成、MDL フィールド定義、CLI ワークフローの詳細については、ドキュメントを参照してください。

---

ワークフロー 1：データに関する質問への回答

ステップ 1 — コンテキストを収集する

状況	コマンド
デフォルト	wren memory fetch -q "<question>"
特定のモデルのカラムが必要	wren memory fetch -q "..." --model <name> --threshold 0
メモリがインストールされていない	プロジェクトディレクトリの target/mdl.json を読む、または wren context show を実行する

これが会話内の最初のクエリである場合は、次も実行します:

wren context instructions

コンテンツが返された場合は、それを デフォルトを上書きするルール として扱い、このセッションの後続のすべてのクエリに適用します。

ステップ 2 — 過去のクエリを想起する

wren memory recall -q "<question>" --limit 3

結果を Few-shot の例として使用します。空の場合はスキップします。

ステップ 2.5 — 複雑さを評価する（SQL を書く前に）

質問が次の いずれか を含む場合は、分解を検討します:

• 複数のメトリクスや集計（例: 「解約率 AND 拡張収益」）
• 多段階の計算（例: 「前月比成長率」）
• セグメント間の比較（例: 「プラン階層別、地域別」）
• ベースライン + 変化を必要とする時系列分析（例: 「リテンションカーブ」）

分解戦略:

1. サブ質問を特定します（例: 「開始時の総購読者数」+「解約した購読者」→ 解約率）
2. 各サブ質問について:
   • wren memory recall -q "<sub-question>" — 類似のパターンが存在するか確認します
   • シンプルな SQL を書いて実行します
   • 結果を記録します
3. サブ結果を統合して元の質問に答えます

分解すべきでない場合:

• GROUP BY を伴う単一テーブルの集計 — SQL をそのまま書きます
• MDL のリレーションシップがすでに定義しているシンプルな JOIN
• memory recall がほぼ完全一致を返す質問

これは厳密なルールではなく判断です。単一のクエリに自信があるなら、 そのまま進めてください。失敗したときにデバッグが難しい SQL の場合に分解します。

ステップ 3 — SQL を書き、検証し、実行する

シンプルなクエリの場合（単一テーブル、または MDL で定義されたシンプルな JOIN、単純な集計）: 直接実行します:

wren --sql 'SELECT c_name, SUM(o_totalprice) FROM orders
JOIN customer ON orders.o_custkey = customer.c_custkey
GROUP BY 1 ORDER BY 2 DESC LIMIT 5'

複雑なクエリの場合（MDL のリレーションシップでカバーされない自明でない JOIN、サブクエリ、多段階のロジック）: まず dry-plan で検証します:

wren dry-plan --sql 'SELECT ...'

展開された SQL の出力を確認します:

• 正しいモデルとカラムが参照されていますか？
• JOIN は期待どおりのリレーションシップと一致していますか？
• CTE は正しく展開されていますか？

展開された SQL が誤っているように見える場合は、実行する前に修正します。 正しいように見える場合は、続行します:

wren --sql 'SELECT ...'

SQL のルール:

• データベースのテーブルではなく、MDL のモデル名を対象にします
• ダイアレクトに依存しない SQL を書きます — エンジンが変換します

ステップ 4 — 保存して続行する

実行が成功したら、デフォルトでクエリを保存します:

wren memory store --nl "<user's original question>" --sql "<the SQL>"

保存をスキップするのは次の場合のみ:

• クエリが失敗した、またはエラーを返した
• ユーザーが結果は間違っていると述べた
• クエリが探索的である（分析句のない SELECT * ... LIMIT N）
• 自然言語の質問がなく、生の SQL だけである
• ユーザーが明示的に保存しないよう求めた

CLI は探索的なクエリを自動検出します — 実行後に保存のヒントが 表示されない場合、そのクエリは探索的であると分類されています。

結果	アクション
ユーザーが正しいと確認	保存
ユーザーがフォローアップを続ける	保存してからフォローアップに対応
ユーザーが何も言わない（ただし質問に明確な NL の説明があった）	保存
ユーザーが間違っていると述べる	保存しない — SQL を修正
クエリエラー	後述のエラーからの復旧を参照

---

ワークフロー 2: エラーからの復旧

「table not found」

1. モデル名を確認します: wren memory fetch -q "<name>" --type model --threshold 0
2. MDL が存在するか確認します: ls target/mdl.json（または wren context show）
3. カラムを確認します: wren memory fetch -q "<column>" --model <name> --threshold 0

接続エラー

1. アクティブなプロファイルを確認します: wren profile debug
2. データソースと接続のフィールドが正しいか確認します
3. テストします: wren --sql "SELECT 1"
4. 有効なデータソースの値: postgres（Aurora Postgres 用）、mysql（Aurora MySQL 用）、bigquery、snowflake、clickhouse、trino、mssql、databricks、redshift、spark、athena、oracle、duckdb
5. プロファイルが存在しない場合は作成します: wren profile add --ui（または --interactive / --from-file）

SQL 構文／計画エラー（拡張版）

レイヤー 1：失敗箇所を特定する

wren dry-plan --sql "<failed SQL>"

dry-plan の結果	失敗レイヤー	次のステップ
dry-plan が失敗する	MDL／セマンティック	→ レイヤー 2A
dry-plan は成功し、実行が失敗する	DB／方言	→ レイヤー 2B

レイヤー 2A：MDL レベルの診断（dry-plan が失敗した場合）

dry-plan のエラーメッセージから、問題の内容を正確に特定できます。

エラーパターン	診断	修正方法
column 'X' not found in model 'Y'	列名が誤っています	wren memory fetch -q "X" --model Y --threshold 0 を実行して正しい名前を探します
model 'X' not found	モデル名が誤っています	wren memory fetch -q "X" --type model --threshold 0
ambiguous column 'X'	複数のモデルに同じ列が存在します	モデル名で修飾します：ModelName.column
JOIN を含む計画エラー	MDL でリレーションシップが定義されていません	コンテキスト内で利用可能なリレーションシップを確認します

重要な原則：一度に修正する問題は 1 つだけにします。修正のたびに dry-plan を再実行し、 新たなエラーが発生していないか確認します。

レイヤー 2B：DB レベルの診断（dry-plan は OK で、実行が失敗した場合）

DB のエラーと dry-plan の出力を組み合わせることで、問題を特定できます。

1. dry-plan で展開された SQL を読みます。これは DB で実際に実行される SQL です。
2. DB のエラーメッセージと照らし合わせます。

エラーパターン	診断	修正方法
型の不一致	列の型が想定と異なります	コンテキスト内で列の型を確認し、明示的な CAST を追加します
未対応の関数	方言固有の関数です	方言に依存しない代替手段を使用します
アクセスが拒否されました	テーブル／スキーマへのアクセスに問題があります	接続認証情報を確認します
タイムアウト	クエリの負荷が高すぎます	JOIN を減らす、フィルターを追加する、LIMIT を指定するなどして簡略化します

小規模なモデルの場合：エラーメッセージが不明瞭な場合は、失敗する最小の断片までクエリを簡略化してみてください。 サブクエリを個別に実行し、失敗する部分を特定します。

CTE の書き換えパイプラインと追加のエラーパターンについては、references/wren-sql.md を参照してください。

---

ワークフロー 3：新しいデータソースへの接続

1. プロファイルを追加します：wren profile add --ui（または --interactive／--from-file）
2. 接続をテストします：wren profile debug
3. クエリをテストします：wren --sql "SELECT 1"
4. プロジェクトを初期化します：wren context init
5. マニフェストをビルドします：wren context build
6. インデックスを作成します：wren memory index
7. 検証します：wren --sql "SELECT * FROM <model> LIMIT 5"

---

ワークフロー 4：MDL の変更後

モデルの YAML ファイルを更新したら、再ビルドしてインデックスを再作成します。

# 1. Validate changes
wren context validate

# 2. Rebuild manifest
wren context build

# 3. Re-index schema memory
wren memory index

# 4. Verify
wren --sql "SELECT * FROM <changed_model> LIMIT 1"

---

コマンドの判断ツリー

Get data back           → wren --sql "..."
Aggregation across dims → wren cube query --cube <name> --measures <m> (if cube defined)
See translated SQL only → wren dry-plan --sql "..." (accepts -d <datasource> if no active profile)
Validate against DB     → wren dry-run --sql "..."
Schema context          → wren memory fetch -q "..."
Filter by type/model    → wren memory fetch -q "..." --type T --model M --threshold 0
Store confirmed query   → wren memory store --nl "..." --sql "..."
Few-shot examples       → wren memory recall -q "..."
Index stats             → wren memory status
Re-index after MDL change → wren memory index
Show project context    → wren context show
Rebuild manifest        → wren context build
Check profile           → wren profile debug
Switch profile          → wren profile switch <name>

---

Cube クエリのワークフロー

ユーザーが集計に関する質問（例：「月別の売上合計」、「上位の顧客」）をした場合は、生の SQL を作成する前に、MDL でキューブが定義されているか確認します。

ステップ 1：キューブを見つける

wren cube list

キューブが存在し、ユーザーの質問に対応できる場合は、生の SQL よりもキューブクエリを優先します。 エラー率を下げられます。特に小規模／ローカルモデルでは、エージェントが GROUP BY／DATE_TRUNC を手作業で記述する必要がありません。

ステップ 2：キューブの構造を調べる

wren cube describe <cube_name>

キューブの baseObject、メジャー（式を含む）、ディメンション、 時間ディメンション、階層が表示されます。

ステップ 3：ユーザーの質問をキューブのメジャーとディメンションに対応付ける

ユーザーの表現	対応先
"total revenue"	--measures revenue
"by month"	--time-dimension "created_at:month"
"in 2024"	--time-dimension "created_at:month:2024-01-01,2025-01-01"
"for completed orders"	--filter "status:eq:completed"
"top N customers"	--dimensions customer --limit N

ステップ 4：CLI フラグまたは JSON 入力で実行する

CLI フラグ：

wren cube query \
  --cube order_metrics \
  --measures revenue,order_count \
  --time-dimension "created_at:month:2024-01-01,2025-01-01" \
  --filter "status:eq:completed" \
  --limit 100

JSON 入力（エージェントが構造化クエリを生成する場合に便利です）：

echo '{"cube":"order_metrics","measures":["revenue"]}' | wren cube query --from -

--sql-only を追加すると、実行せずに生成された SQL を出力できます。リモートウェアハウスで実行料金を支払う前の確認に便利です。

ステップ 5：エラーからの復旧

エラー	対処方法
Unknown measure 'X'	利用可能なメジャーを確認するには、wren cube describe <cube> を実行します
Unknown dimension 'X'	利用可能なディメンションを確認するには、wren cube describe <cube> を実行します
Cube 'X' not found	wren cube list を実行します
Circular dependency detected	派生メジャーが自身を参照しています。キューブの YAML を確認してください

cube query を使用しない場合

次の場合は wren --sql に切り替えてください。

• 複数のモデルにまたがるカスタム JOIN
• ウィンドウ関数、CTE、サブクエリ
• 集計を含まないクエリ
• MDL にキューブが定義されていない場合

---

集計の判断フローチャート

User question → Is it an aggregation question?
                (SUM, COUNT, AVG, GROUP BY, "by month", "per customer", ...)
  ├── Yes → Are cubes defined? (`wren cube list` once at start of session)
  │         ├── Yes → Does a cube cover the question? (`wren cube describe`)
  │         │         ├── Yes → Use `wren cube query` (preferred — lower error rate)
  │         │         └── No  → Write raw SQL with `wren --sql`
  │         └── No  → Write raw SQL with `wren --sql`
  └── No  → Write raw SQL with `wren --sql` (look for memory recall first)

---

避けるべきこと

• モデル名や列名を推測しないでください。まずコンテキストを確認してください
• 失敗したクエリや、ユーザーが誤りだと指摘したクエリを保存しないでください
• 明確な自然言語の質問を伴う成功したクエリの保存を省略しないでください。デフォルトでは保存します
• クエリを実行するたびに再インデックスしないでください。MDL を変更したときに一度だけ実行してください
• シェルの履歴を共有している場合、--connection-info を使ってパスワードを渡さないでください。プロファイル（wren profile add）または --connection-file を使用してください