WrenAI 自然语言查询完全教程：从接入数据库到首个 Text-to-SQL 的 15 分钟路径-开发者社区

WrenAI 自然语言查询完全教程：从接入数据库到首个 Text-to-SQL 的 15 分钟路径

【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20+ data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI

手写 SQL 问数太麻烦？WrenAI 是一款开源自然语言查询引擎：用 MDL 语义层与本地记忆索引为自然语言问题做语义对齐，生成并执行受治理的 SQL，覆盖 PostgreSQL、ClickHouse、Snowflake 等 22+ 数据源，适合想把现有数据库变成问数入口的数据工程师，以及要接入 AI agent 的开发者。本文走通从安装 CLI 到拿到首个查询结果的最短路径。

认识 WrenAI：动手前建立的心智模型

它是什么：受治理的 Text-to-SQL，而不是让模型猜 SQL

WrenAI 的定位是开源 GenBI（生成式 BI）引擎，Apache-2.0 协议。与“把表结构丢给 LLM 直接写 SQL”不同，它生成的每条 SQL 都有前置约束：先对着 MDL 语义层做计划——用你定义过的模型名、字段语义和关系，而不是裸表名；再通过 dry-plan 预校验，失败时返回带修复提示的结构化错误，而不是一个看似正确的结果。执行层是基于 Apache DataFusion 的 Rust 引擎，可连接 22+ 数据源。

支撑它的两层知识：MDL 语义层与 AI 上下文层

MDL 语义层：以models/、views/、cubes/、relationships.yml的形式存在，用业务语言描述数据含义——模型、字段、连接关系、指标口径，全部可 Git 版本化、可评审。
AI 上下文层：knowledge/rules/存放业务规则（例如“revenue 永远指订单金额，不是某个支付渠道字段”）；.wren/memory/是本地向量索引（LanceDB），沉淀过往“自然语言 → SQL”的成对示例，新问题进来时先召回相似历史查询。

上下文层越完整，SQL 出错的概率越低，这是它与单提示词 text-to-SQL 脚本的本质区别。

一次查询的完整旅程

一个自然语言问题到数据库之间是一条固定管线：wren memory fetch检索与问题相关的表和字段，wren memory recall召回相似历史查询，agent 用 MDL 名称写出 SQL，引擎校验后执行，结果确认正确后用wren memory store回写记忆，下一次召回因此更准。

快速上手：安装、建 profile 到项目成型

前置依赖只有四项，其余由 CLI 自带：

依赖项	版本要求	用途
Python	3.11+	运行 wren CLI
Node.js / npm	18+	用 npx 安装 agent 技能桩
AI agent（如 Claude Code）	任一	驱动 MDL 生成与日常自然语言查询
查询目标数据库	PostgreSQL / DuckDB 等	DuckDB 随 wrenai 附带，无需另装

以下路径假设你手头已有一个数据库（DuckDB 文件或 Postgres）。没有现成库也可用项目内置的 jaffle_shop 示例，快速开始文档里有对应流程。

创建虚拟环境并安装 CLI（memory 附加组件启用记忆索引，main 附加组件提供交互表单与浏览器 profile 页）：

python3 -m venv ~/.venvs/wren source ~/.venvs/wren/bin/activate pip install "wrenai[memory,main]"

预期：wren version打印已装版本号；其他数据源按需追加 extras，例如pip install "wrenai[postgres]"。

再让 agent 认识 WrenAI：安装约 50 行的发现桩，会自动检测你已安装的 AI 客户端：

npx skills add Canner/WrenAI

预期：输出 wren 技能的安装位置；具体工作流指南由 agent 用wren skills get <name>从 CLI 按需拉取，内容与已装版本始终一致。

创建连接 profile。也可以wren profile add my-db --ui用浏览器表单填写，这里演示文件方式。写好 profile.yml 后导入并验证：

datasource: duckdb url: /绝对路径/包含/directory # DuckDB 的 url 必须是包含 .duckdb 文件的目录，而非文件本身

wren profile add my-db --from-file profile.yml wren profile debug

预期：debug打印连接测试通过；wren profile list中 my-db 为活动状态。

然后建项目目录并初始化 Wren 项目：

mkdir my-wren-project && cd my-wren-project wren context init wren context set-profile my-db

预期：生成wren_project.yml、models/、views/、cubes/、knowledge/、relationships.yml骨架；最后一条命令把项目锁定到 my-db 连接，之后别处切换 profile 也不会把本项目的查询引走。

最后让 agent 生成 MDL：在项目目录打开 agent，说“用 /wren 技能探索数据库，为核心表生成 MDL，跳过中间表与原始表”。agent 按generate-mdl指南完成表发现、类型规范化、关系推断、manifest 构建，并以wren memory index收尾。预期：wren context show列出模型与关系，wren memory status显示记忆索引已就绪。

核心功能实战：三个高频场景

场景一：自然语言提问直接出结果

项目就绪后，直接向 agent 提问：“本季度销售额 Top 10 客户是谁？”。agent 会按上面的管线执行：取上下文、召回相似历史、写 SQL、经wren query --sql "..."执行。预期：返回结果表与所执行的 SQL；确认结果正确后用wren memory store --nl "问题" --sql "SQL"存档，下次同类问题直接命中历史，省去重新推理。

💡 若所用 agent 能力偏弱，可用wren ask "<问题>" --guided让 CLI 组装提示词与上下文；强 agent 则用--direct。

场景二：用 cube 固定指标口径

如果“revenue”“订单数”在不同人口径不一、agent 反复出错，就把它们定义为 cube——声明了模型、度量、维度与时间粒度的指标对象。让 agent 写好 cube 后，可直接用 CLI 查询：

wren cube query --cube revenue --measures total,order_count --time-dimension "order_date:month"

预期：返回按月聚合结果；加--dimensions status或--filter "status:eq:completed"可进一步切片。此后所有涉及这些指标的自然语言提问都走同一口径，不再各算各的。

场景三：把确认过的答案变成可分享的看板

某个周报口径确定后，让 agent 执行genbi指南：构建浏览器端应用（数据以快照内置、无需后端），先wren genbi verify预检，再wren genbi open本地预览。样式确认后，把部署令牌（如VERCEL_TOKEN）写入~/.wren/.env，让它执行部署。预期：先拿到本地预览地址（如http://127.0.0.1:8848/），部署后得到可分享 URL，默认指向预览环境，明确说“ship it to production”才会推到正式环境。

排坑手册：五个高频问题与解法

现象	原因	解法
首次运行`wren memory index`卡住数十秒	首次加载约 800MB 的 lancedb/torch 原生库，macOS 还会触发一次性安全扫描	等一次跑完即可，后续命令速度正常；或安装后先手动执行任意 memory 命令预热
SQL 能执行，但结果与业务口径不符	agent 按裸 schema 写 SQL，缺业务定义（枚举值、单位、连接口径）	补`knowledge/rules/`与 MDL 字段描述，再执行`wren context build`和`wren memory index`
修改模型或关系后查询行为没变	manifest 未重建，仍在用旧的`mdl.json`	按序执行`wren context validate`→`wren context build`→`wren memory index`
`wren profile debug`时 duckdb 连不上	url 指向了 .duckdb 文件本身	DuckDB 的 url 应填包含 .duckdb 文件的目录
`pip install wrenai`缓慢或失败	国内网络访问 PyPI / HuggingFace 受限	为 pip 配置国内镜像源；用`HF_ENDPOINT`环境变量指定 HuggingFace 镜像端点