wren-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wren Engine CLI — Agent Workflow Guide

Wren Engine CLI — Agent工作流指南

Version check

版本检查

Silently fetch

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json

. Compare the

wren-usage

key with this skill's version (from the frontmatter above). If the remote version is newer, notify the user before proceeding:

A newer version of the wren-usage skill is available. Update with:
npx skills add Canner/WrenAI --skill wren-usage
The CLI auto-detects your installed agent. To target a specific one, add
--agent <name>
(e.g.,
claude-code
,
cursor
,
windsurf
,
cline
).

Then continue with the workflow below regardless of update status.

静默获取

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json

。将其中的

wren-usage

键值与本技能的版本（来自上方的前置信息）进行对比。如果远程版本更新，在继续操作前通知用户：

wren-usage技能的新版本已可用。执行以下命令更新：
npx skills add Canner/WrenAI --skill wren-usage
CLI会自动检测已安装的Agent。若要指定特定Agent，添加
--agent <name>
参数（例如：
claude-code
,
cursor
,
windsurf
,
cline
）。

无论是否更新，之后都继续执行下方的工作流。

Preflight — Verify environment and installation

预检查——验证环境与安装

Goal: Ensure the

wren

CLI is available before entering any workflow.

目标：进入任何工作流前，确保

wren

CLI已可用。

Step 1 — Check Python virtual environment

步骤1——检查Python虚拟环境

Run

python -c "import sys; print(sys.prefix)"

(or equivalent) to determine whether a virtual environment is active.

If no venv is active, warn the user and ask whether to:
- Create one (e.g.,
```
python -m venv .venv && source .venv/bin/activate
```
  )
- Continue without a venv (not recommended — may pollute global packages)

运行

python -c "import sys; print(sys.prefix)"

（或等效命令）判断是否有虚拟环境处于激活状态。

如果无激活的虚拟环境，向用户发出警告并询问是否：
- 创建虚拟环境（例如：
```
python -m venv .venv && source .venv/bin/activate
```
  ）
- 不使用虚拟环境继续操作（不推荐——可能会污染全局包）

Step 2 — Check if

wren-engine

is installed

步骤2——检查

wren-engine

是否已安装

Run

wren --version

. If the command is not found or errors:

Tell the user that the
```
wren
```
CLI is not installed.
Ask if you should help install it.
If the user agrees, determine the datasource extra to install:
Auto-detect from project: Check whether the current directory is inside a wren project (look for
```
wren_project.yml
```
up to the repository root). If found, read the active profile with
```
cat ~/.wren/profiles.yml
```
or look for a datasource hint in the project's profile configuration. Extract the datasource type from there.
Ask the user: If no project is detected or no datasource can be inferred, ask the user which database they plan to connect to. Valid extras:
```
postgres
```
,
```
mysql
```
,
```
bigquery
```
,
```
snowflake
```
,
```
clickhouse
```
,
```
trino
```
,
```
mssql
```
,
```
databricks
```
,
```
redshift
```
,
```
spark
```
,
```
athena
```
,
```
oracle
```
. DuckDB is included by default — no extra needed.

Install with the detected or chosen extra:

bash

# DuckDB (no extra needed)
pip install "wren-engine"

# Other datasources
pip install "wren-engine[<datasource>]"

To also enable semantic memory, interactive prompts, and web UI (recommended):

bash

pip install "wren-engine[<datasource>,main]"
# or for DuckDB:
pip install "wren-engine[main]"

Verify:
```
wren --version
```

wren --version

succeeds, proceed to the relevant workflow below.

The

wren

CLI queries databases through an MDL (Model Definition Language) semantic layer. You write SQL against model names, not raw tables. The engine translates to the target dialect.

Two things drive everything:

Profile — database connection + datasource type, managed via
```
wren profile
```
(stored in
```
~/.wren/profiles.yml
```
)
Project — MDL model definitions in YAML, compiled to
```
target/mdl.json
```
via
```
wren context build
```

The CLI reads the active profile for connection info and datasource. Use

wren profile list

to see which profile is active,

wren profile switch <name>

to change it.

dry-plan

also accepts

--datasource

-d

for transpile-only use without a profile.

For memory-specific decisions, see references/memory.md. For SQL syntax, CTE-based modeling, and error diagnosis, see references/wren-sql.md. For project structure, MDL field definitions, and CLI workflow details, see the documentation.

运行

wren --version

。若命令未找到或报错：

告知用户
```
wren
```
CLI未安装。
询问是否需要协助安装。
如果用户同意，确定要安装的数据源扩展：
从项目自动检测：检查当前目录是否位于wren项目内（向上遍历至仓库根目录，查找
```
wren_project.yml
```
）。如果找到，通过
```
cat ~/.wren/profiles.yml
```
读取活跃配置文件，或从项目配置文件中查找数据源提示。从中提取数据源类型。
询问用户：如果未检测到项目或无法推断数据源，询问用户计划连接的数据库。支持的扩展包括：
```
postgres
```
,
```
mysql
```
,
```
bigquery
```
,
```
snowflake
```
,
```
clickhouse
```
,
```
trino
```
,
```
mssql
```
,
```
databricks
```
,
```
redshift
```
,
```
spark
```
,
```
athena
```
,
```
oracle
```
。 DuckDB默认包含在内——无需额外扩展。

安装检测到或用户选择的扩展：

bash

# DuckDB（无需扩展）
pip install "wren-engine"

# 其他数据源
pip install "wren-engine[<datasource>]"

若要同时启用语义记忆、交互式提示和Web UI（推荐）：

bash

pip install "wren-engine[<datasource>,main]"
# 针对DuckDB的命令：
pip install "wren-engine[main]"

验证：
```
wren --version
```

如果

wren --version

执行成功，继续执行下方对应的工作流。

wren

CLI通过MDL（模型定义语言）语义层查询数据库。你可以针对模型名称编写SQL，而非直接操作原始表。引擎会将SQL转换为目标数据库的方言。

所有操作由两个核心要素驱动：

配置文件（Profile）——数据库连接信息+数据源类型，通过
```
wren profile
```
管理（存储于
```
~/.wren/profiles.yml
```
）
项目（Project）——YAML格式的MDL模型定义，通过
```
wren context build
```
编译为
```
target/mdl.json
```

CLI读取活跃配置文件获取连接信息和数据源。使用

wren profile list

查看活跃配置文件，使用

wren profile switch <name>

切换配置文件。

dry-plan

命令也支持

--datasource

-d

参数，用于仅转换SQL而无需配置文件的场景。

关于记忆相关的决策，请参考references/memory.md。关于SQL语法、基于CTE的建模和错误诊断，请参考references/wren-sql.md。关于项目结构、MDL字段定义和CLI工作流详情，请查看文档。

Workflow 1: Answering a data question

工作流1：解答数据问题

Step 1 — Gather context

步骤1——收集上下文

Situation	Command
Default	`wren memory fetch -q "<question>"`
Need specific model's columns	`wren memory fetch -q "..." --model <name> --threshold 0`
Memory not installed	Read `target/mdl.json` in the project directory, or run `wren context show`

If this is the first query in the conversation, also run:

text

wren context instructions

If it returns content, treat it as rules that override defaults — apply them to all subsequent queries in this session.

场景	命令
默认情况	`wren memory fetch -q "<question>"`
需要特定模型的列	`wren memory fetch -q "..." --model <name> --threshold 0`
未安装记忆功能	读取项目目录下的 `target/mdl.json` ，或运行 `wren context show`

如果是对话中的首次查询，还需运行：

text

wren context instructions

如果返回内容，将其视为覆盖默认规则的自定义规则——在本次会话的所有后续查询中应用这些规则。

Step 2 — Recall past queries

步骤2——召回历史查询

bash

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

Use results as few-shot examples. Skip if empty.

bash

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

将结果作为少样本示例。如果结果为空则跳过此步骤。

Step 2.5 — Assess complexity (before writing SQL)

步骤2.5——评估复杂度（编写SQL前）

If the question involves any of the following, consider decomposing:

Multiple metrics or aggregations (e.g., "churn rate AND expansion revenue")
Multi-step calculations (e.g., "month-over-month growth rate")
Comparisons across segments (e.g., "by plan tier, by region")
Time-series analysis requiring baseline + change (e.g., "retention curve")

Decomposition strategy:

Identify the sub-questions (e.g., "total subscribers at start" + "subscribers who cancelled" → churn rate)
For each sub-question:
- ```
wren memory recall -q "<sub-question>"
```
  — check if a similar pattern exists
- Write and execute a simple SQL
- Note the result
Combine sub-results to answer the original question

When NOT to decompose:

Single-table aggregation with GROUP BY — just write the SQL
Simple JOINs that the MDL relationships already define
Questions where
```
memory recall
```
returns a near-exact match

This is a judgment call, not a rigid rule. If you're confident in a single query, go ahead. Decompose when the SQL would be hard to debug if it fails.

如果问题涉及以下任意情况，考虑拆分问题：

多个指标或聚合操作（例如：“流失率和扩展收入”）
多步计算（例如：“月环比增长率”）
跨细分维度的对比（例如：“按套餐层级、按地区”）
需要基线+变化的时间序列分析（例如：“留存曲线”）

拆分策略：

识别子问题（例如：“期初订阅用户总数” + “已取消订阅的用户数” → 流失率）
针对每个子问题：
- 运行
```
wren memory recall -q "<sub-question>"
```
  ——检查是否存在类似模式
- 编写并执行简单SQL
- 记录结果
合并子问题的结果以解答原始问题

无需拆分的场景：

带GROUP BY的单表聚合——直接编写SQL即可
MDL关系已定义的简单JOIN操作
```
memory recall
```
返回近乎完全匹配的查询

这是基于判断的决策，而非硬性规则。如果你对单个查询有信心，可以直接执行。当SQL出错后难以调试时，再进行拆分。

Step 3 — Write, verify, and execute SQL

步骤3——编写、验证并执行SQL

For simple queries (single table or simple MDL-defined JOINs, straightforward aggregation): Execute directly:

bash

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'

For complex queries (non-trivial JOINs not covered by MDL relationships, subqueries, multi-step logic): Verify first with dry-plan:

bash

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

Check the expanded SQL output:

Are the correct models and columns referenced?
Do the JOINs match expected relationships?
Are CTEs expanded correctly?

If the expanded SQL looks wrong, fix before executing. If it looks correct, proceed:

bash

wren --sql 'SELECT ...'

SQL rules:

Target MDL model names, not database tables
Write dialect-neutral SQL — the engine translates

针对简单查询（单表或MDL定义的简单JOIN、直接的聚合操作）：直接执行：

bash

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验证：

bash

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

检查展开后的SQL输出：

是否引用了正确的模型和列？
JOIN是否符合预期的关系？
CTE是否正确展开？

如果展开后的SQL有误，修复后再执行。如果展开后的SQL正确，继续执行：

bash

wren --sql 'SELECT ...'

SQL规则：

以MDL模型名称为目标，而非数据库表
编写与方言无关的SQL——引擎会自动转换

Step 4 — Store and continue

步骤4——存储查询并继续

After successful execution, store the query by default:

bash

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

Skip storing only when:

The query failed or returned an error
The user said the result is wrong
The query is exploratory (
```
SELECT * ... LIMIT N
```
without analytical clauses)
There is no natural language question — just raw SQL
The user explicitly asked not to store

The CLI auto-detects exploratory queries — if you see no store hint after execution, the query was classified as exploratory.

Outcome	Action
User confirms correct	Store
User continues with follow-up	Store, then handle follow-up
User says nothing (but question had clear NL description)	Store
User says wrong	Do NOT store — fix the SQL
Query error	See Error recovery below

执行成功后，默认存储该查询：

bash

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

仅在以下情况跳过存储：

查询失败或返回错误
用户表示结果有误
查询为探索性操作（无分析子句的
```
SELECT * ... LIMIT N
```
）
无自然语言问题——仅为原始SQL
用户明确要求不存储

CLI会自动检测探索性查询——如果执行后未提示存储，则该查询已被归类为探索性查询。

结果	操作
用户确认结果正确	存储
用户提出后续问题	存储，然后处理后续问题
用户未反馈（但问题有明确的自然语言描述）	存储
用户表示结果错误	不存储——修复SQL
查询出错	查看下方的错误恢复流程

Workflow 2: Error recovery

工作流2：错误恢复

"table not found"

"table not found"（表未找到）

Verify model name:

wren memory fetch -q "<name>" --type model --threshold 0

Check MDL exists:
```
ls target/mdl.json
```
(or
```
wren context show
```
)

Verify column:

wren memory fetch -q "<column>" --model <name> --threshold 0

验证模型名称：

wren memory fetch -q "<name>" --type model --threshold 0

检查MDL是否存在：
```
ls target/mdl.json
```
（或
```
wren context show
```
）

验证列：

wren memory fetch -q "<column>" --model <name> --threshold 0

Connection error

连接错误

Check active profile:
```
wren profile debug
```
Verify datasource and connection fields are correct
Test:
```
wren --sql "SELECT 1"
```

Valid datasource values:

postgres

mysql

bigquery

snowflake

clickhouse

trino

mssql

databricks

redshift

spark

athena

oracle

duckdb

If no profile exists, create one:

wren profile add --ui

(or

--interactive

--from-file

)

检查活跃配置文件：
```
wren profile debug
```
验证数据源和连接字段是否正确
测试：
```
wren --sql "SELECT 1"
```

有效的数据源值：

postgres

mysql

bigquery

snowflake

clickhouse

trino

mssql

databricks

redshift

spark

athena

oracle

duckdb

如果配置文件不存在，创建一个：
```
wren profile add --ui
```
（或
```
--interactive
```
/
```
--from-file
```
）

SQL syntax / planning error (enhanced)

SQL语法/规划错误（增强版）

Layer 1: Identify the failure point

第一层：定位失败点

bash

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

dry-plan result	Failure layer	Next step
dry-plan fails	MDL / semantic	→ Layer 2A
dry-plan succeeds, execution fails	DB / dialect	→ Layer 2B

bash

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

dry-plan结果	失败层级	下一步操作
dry-plan失败	MDL/语义层	→ 第二层A
dry-plan成功，但执行失败	数据库/方言层	→ 第二层B

Layer 2A: MDL-level diagnosis (dry-plan failed)

第二层A：MDL层面诊断（dry-plan失败）

The dry-plan error message tells you exactly what's wrong:

Error pattern	Diagnosis	Fix
`column 'X' not found in model 'Y'`	Wrong column name	`wren memory fetch -q "X" --model Y --threshold 0` to find correct name
`model 'X' not found`	Wrong model name	`wren memory fetch -q "X" --type model --threshold 0`
`ambiguous column 'X'`	Column exists in multiple models	Qualify with model name: `ModelName.column`
Planning error with JOIN	Relationship not defined in MDL	Check available relationships in context

Key principle: Fix ONE issue at a time. Re-run dry-plan after each fix to see if new errors surface.

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中未定义该关系	查看上下文中可用的关系

核心原则：一次只修复一个问题。每次修复后重新运行dry-plan，查看是否出现新错误。

Layer 2B: DB-level diagnosis (dry-plan OK, execution failed)

第二层B：数据库层面诊断（dry-plan正常，执行失败）

The DB error + dry-plan output together pinpoint the issue:

Read the dry-plan expanded SQL — this is what actually runs on the DB
Compare with the DB error message:

Error pattern	Diagnosis	Fix
Type mismatch	Column type differs from assumed	Check column type in context, add explicit CAST
Function not supported	Dialect-specific function	Use dialect-neutral alternative
Permission denied	Table/schema access	Check connection credentials
Timeout	Query too expensive	Simplify: reduce JOINs, add filters, LIMIT

For small models: If the error message is unclear, try simplifying the query to the smallest failing fragment. Execute subqueries independently to isolate which part fails.

For the CTE rewrite pipeline and additional error patterns, see references/wren-sql.md.

数据库错误信息+dry-plan输出可共同定位问题：

查看dry-plan展开后的SQL——这是实际在数据库上运行的语句
结合数据库错误信息分析：

错误模式	诊断	修复方案
类型不匹配	列类型与预期不符	查看上下文中的列类型，添加显式CAST转换
函数不支持	使用了方言特定函数	使用与方言无关的替代函数
权限不足	无表/ schema访问权限	检查连接凭证
超时	查询开销过大	简化查询：减少JOIN、添加过滤条件、使用LIMIT

针对小型模型：如果错误信息不明确，尝试将查询简化为最小的失败片段。独立执行子查询以隔离失败部分。

关于CTE重写流程和更多错误模式，请参考references/wren-sql.md。

Workflow 3: Connecting a new data source

工作流3：连接新数据源

Add a profile:

wren profile add --ui

(or

--interactive

--from-file

)

Test connection:
```
wren profile debug
```
Test query:
```
wren --sql "SELECT 1"
```
Initialize project:
```
wren context init
```
Build manifest:
```
wren context build
```
Index:
```
wren memory index
```

Verify:

wren --sql "SELECT * FROM <model> LIMIT 5"

添加配置文件：

wren profile add --ui

（或

--interactive

--from-file

）

测试连接：
```
wren profile debug
```
测试查询：
```
wren --sql "SELECT 1"
```
初始化项目：
```
wren context init
```
构建清单：
```
wren context build
```
索引：
```
wren memory index
```

验证：

wren --sql "SELECT * FROM <model> LIMIT 5"

Workflow 4: After MDL changes

工作流4：MDL变更后

When model YAML files are updated, rebuild and re-index:

bash

undefined

当模型YAML文件更新后，重新构建并重新索引：

bash

undefined

1. Validate changes

1. 验证变更

wren context validate

2. Rebuild manifest

2. 重建清单

wren context build

3. Re-index schema memory

3. 重新索引Schema记忆

wren memory index

4. Verify

4. 验证

wren --sql "SELECT * FROM <changed_model> LIMIT 1"

---

wren --sql "SELECT * FROM <changed_model> LIMIT 1"

---

Command decision tree

命令决策树

text

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>

text

获取数据结果           → wren --sql "..."
跨维度聚合 → wren cube query --cube <name> --measures <m>（如果已定义cube）
仅查看转换后的SQL → wren dry-plan --sql "..."（如果无活跃配置文件，可使用-d <datasource>参数）
针对数据库验证 → wren dry-run --sql "..."
Schema上下文 → wren memory fetch -q "..."
按类型/模型过滤 → wren memory fetch -q "..." --type T --model M --threshold 0
存储已确认的查询 → wren memory store --nl "..." --sql "..."
少样本示例 → wren memory recall -q "..."
索引状态 → wren memory status
MDL变更后重新索引 → wren memory index
查看项目上下文 → wren context show
重建清单 → wren context build
检查配置文件 → wren profile debug
切换配置文件 → wren profile switch <name>

Cube Query Workflow

Cube查询工作流

When the user asks an aggregation question (e.g., "total revenue by month", "top customers"), check if the MDL defines cubes before writing raw SQL.

当用户提出聚合类问题（例如：“按月统计总收入”“顶级客户”），在编写原始SQL前，先检查MDL是否定义了cube。

Step 1: Discover cubes

步骤1：发现cube

bash

wren cube list

If cubes exist and cover the user's question, prefer cube query over raw SQL. Lower error rate, especially for small / local models — agents don't have to hand-write GROUP BY / DATE_TRUNC.

bash

wren cube list

如果存在cube且覆盖用户的问题，优先使用cube查询而非原始SQL。错误率更低，尤其适用于小型/本地模型——Agent无需手动编写GROUP BY / DATE_TRUNC。

Step 2: Inspect cube structure

步骤2：查看cube结构

bash

wren cube describe <cube_name>

Shows the cube's baseObject, measures (with expressions), dimensions, time dimensions, and hierarchies.

bash

wren cube describe <cube_name>

展示cube的baseObject、度量（含表达式）、维度、时间维度和层级结构。

Step 3: Match user's question to cube measures + dimensions

步骤3：匹配用户问题与cube的度量+维度

User phrase	Maps to
"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`

用户表述	对应参数
“总收入”	`--measures revenue`
“按月”	`--time-dimension "created_at:month"`
“2024年”	`--time-dimension "created_at:month:2024-01-01,2025-01-01"`
“针对已完成订单”	`--filter "status:eq:completed"`
“前N个客户”	`--dimensions customer --limit N`

Step 4: Execute via CLI flags OR JSON input

步骤4：通过CLI参数或JSON输入执行

CLI flags:

bash

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 input (good for agent-generated structured queries):

bash

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

Add

--sql-only

to print the generated SQL without executing — useful for verification before paying for execution on a remote warehouse.

CLI参数方式：

bash

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输入方式（适用于Agent生成的结构化查询）：

bash

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

添加

--sql-only

参数可仅打印生成的SQL而不执行——适用于远程仓库执行前的验证，避免产生费用。

Step 5: Error recovery

步骤5：错误恢复

Error	Action
`Unknown measure 'X'`	`wren cube describe <cube>` for available measures
`Unknown dimension 'X'`	`wren cube describe <cube>` for available dimensions
`Cube 'X' not found`	`wren cube list`
`Circular dependency detected`	Derived measure references itself — inspect the cube YAML

错误	操作
`Unknown measure 'X'`	运行 `wren cube describe <cube>` 查看可用度量
`Unknown dimension 'X'`	运行 `wren cube describe <cube>` 查看可用维度
`Cube 'X' not found`	运行 `wren cube list` 查看所有cube
`Circular dependency detected`	派生度量引用了自身——检查cube的YAML文件

When NOT to use cube query

不使用cube查询的场景

Fall back to

wren --sql

when:

Custom JOINs across multiple models
Window functions, CTEs, or subqueries
Queries with no aggregation
No cubes defined in the MDL

当出现以下情况时，回退到

wren --sql

：

跨多个模型的自定义JOIN
窗口函数、CTE或子查询
无聚合操作的查询
MDL中未定义任何cube

Aggregation decision tree

聚合决策树

text

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)

text

用户问题 → 是否为聚合类问题？
               （SUM、COUNT、AVG、GROUP BY、“按月”“按客户”等）
  ├── 是 → 是否已定义cube？（会话开始时运行一次`wren cube list`）
  │         ├── 是 → 是否有cube覆盖该问题？（运行`wren cube describe`）
  │         │         ├── 是 → 使用`wren cube query`（优先选择——错误率更低）
  │         │         └── 否  → 使用`wren --sql`编写原始SQL
  │         └── 否  → 使用`wren --sql`编写原始SQL
  └── 否  → 使用`wren --sql`编写原始SQL（先查看memory recall结果）

Things to avoid

注意事项

Do not guess model or column names — check context first
Do not store failed queries or queries the user said are wrong
Do not skip storing successful queries with a clear NL question — default is to store
Do not re-index before every query — once per MDL change
Do not pass passwords via
```
--connection-info
```
if shell history is shared — use profiles (
```
wren profile add
```
) or
```
--connection-file
```

不要猜测模型或列名——先检查上下文
不要存储失败的查询或用户认为错误的查询
不要跳过存储带有明确自然语言问题的成功查询——默认存储
不要在每次查询前重新索引——仅在MDL变更后执行一次
如果shell历史记录共享，不要通过
```
--connection-info
```
传递密码——使用配置文件（
```
wren profile add
```
）或
```
--connection-file
```
参数

wren-usage

Original

Translation

Wren Engine CLI — Agent Workflow Guide

Wren Engine CLI — Agent工作流指南

Version check

版本检查

Preflight — Verify environment and installation

预检查——验证环境与安装

Step 1 — Check Python virtual environment

步骤1——检查Python虚拟环境

Step 2 — Check if wren-engine is installed

步骤2——检查wren-engine是否已安装

Workflow 1: Answering a data question

工作流1：解答数据问题

Step 1 — Gather context

步骤1——收集上下文

Step 2 — Recall past queries

步骤2——召回历史查询

Step 2.5 — Assess complexity (before writing SQL)

步骤2.5——评估复杂度（编写SQL前）

Step 3 — Write, verify, and execute SQL

步骤3——编写、验证并执行SQL

Step 4 — Store and continue

步骤4——存储查询并继续

Workflow 2: Error recovery

工作流2：错误恢复

"table not found"

"table not found"（表未找到）

Connection error

连接错误

SQL syntax / planning error (enhanced)

SQL语法/规划错误（增强版）

Layer 1: Identify the failure point

第一层：定位失败点

Layer 2A: MDL-level diagnosis (dry-plan failed)

第二层A：MDL层面诊断（dry-plan失败）

Layer 2B: DB-level diagnosis (dry-plan OK, execution failed)

第二层B：数据库层面诊断（dry-plan正常，执行失败）

Workflow 3: Connecting a new data source

工作流3：连接新数据源

Workflow 4: After MDL changes

工作流4：MDL变更后

1. Validate changes

1. 验证变更

2. Rebuild manifest

2. 重建清单

3. Re-index schema memory

3. 重新索引Schema记忆

4. Verify

4. 验证

Command decision tree

命令决策树

Cube Query Workflow

Cube查询工作流

Step 1: Discover cubes

步骤1：发现cube

Step 2: Inspect cube structure

步骤2：查看cube结构

Step 3: Match user's question to cube measures + dimensions

步骤3：匹配用户问题与cube的度量+维度

Step 4: Execute via CLI flags OR JSON input

步骤4：通过CLI参数或JSON输入执行

Step 5: Error recovery

步骤5：错误恢复

When NOT to use cube query

不使用cube查询的场景

Aggregation decision tree

聚合决策树

Things to avoid

注意事项

Step 2 — Check if
`wren-engine`
is installed

步骤2——检查
`wren-engine`
是否已安装