5分钟把数据库变成自然语言问答助手：WrenAI 新手实操教程

5分钟把数据库变成自然语言问答助手：WrenAI 新手实操教程

【免费下载链接】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

想象一下：你问 AI“上季度销售额是多少？”，它自信地吐出一段 SQL，结果把退款也算了进去——因为status = 4到底代表什么，数据库自己并不知道。这就是大多数 text-to-SQL 工具翻车的地方：Agent 只能看到表结构，看不到业务含义。

WrenAI 就是一个为此而生的开源 GenBI（生成式商业智能）引擎：它把你的数据语义、指标定义和表关系整理成一层 Agent 可以信任的"上下文"，再让 AI 用自然语言问数、生成可信 SQL，直到一键部署可分享的图表看板。支持 BigQuery、Snowflake、PostgreSQL、ClickHouse 等 22+ 数据源，核心引擎基于 Apache DataFusion，Apache-2.0 协议免费自托管。

先问一个问题，15 分钟跑通全流程

WrenAI 的设计思路是"Agent 驱动"：你负责提需求，AI 编码 Agent 负责干活。下面这条路径可以直接照着做，约 15 分钟完成。

第 1 步：装一个 CLI

只需一条命令（Python 3.11+ 环境）：

pip install wrenai

DuckDB 引擎默认内置，所以哪怕你手头没有任何数据库，也能立刻上手。跑一下wren version确认装好了。

第 2 步：给 AI 装"技能"

在你常用的 AI 编码客户端（Claude Code、Cursor、Codex 等）里执行：

npx skills add Canner/WrenAI

它会自动检测你装了哪个 Agent，并安装一个很小的技能存根。以后 Agent 需要哪份操作指南，都会现场向 CLI 索取，永远和安装版本匹配。

第 3 步：让 Agent 替你连库、建模

打开 Agent，直接说人话即可，比如：

"用 Wren 帮我连上我的 Postgres 库，生成项目脚手架。"

Agent 会自动创建连接 profile、初始化项目、检查数据库结构，并用 MDL 文件描述你的表和关联关系。整个过程中你只需要回答几个业务含义的问题，例如"哪些表是团队真正在用的"。如果你没有自己的数据库，让它用自带的jaffle_shop电商样例数据，同样能跑通全流程。

第 4 步：问出第一个业务问题

"这个季度销售额 Top 10 的客户是谁？"

Agent 会读取 MDL 上下文、回忆过往相似查询、写出受治理的 SQL，再交给 Wren 引擎执行并返回结果。你几乎不需要碰任何 SQL。

它凭什么"可信"：MDL 语义层是核心答案

WrenAI 的可靠性不靠提示词玄学，而靠一份叫 MDL（Modeling Definition Language）的"语义合同"。你可以把它理解为三件事：

• 数据长什么样：模型、字段、类型、主键、表间关联，与具体数仓解耦；
• 数据是什么意思：字段别名、计算字段、枚举含义（比如status = 4是退款）、团队认可的口径；
• 哪些计算可复用：cube 与指标定义一次，"营收"在每张报表里含义都一致。

关键在于，这些定义全部是项目里的可读 YAML 文件，可以直接进 Git：可评审、可回滚、可 diff。新人或新 Agent 加入时无需重新"学习"你的业务，读文件就行。定义变了，改文件、提交、重建即可，全程透明。

再往外一层是 AI 上下文层：本地记忆索引会记住过去成功的"自然语言—SQL"配对，问得越多，后续相似问题召回越准。官方把上下文分成结构、语义、业务、操作、行为五层，前三层由 MDL 承载，后两层由记忆与示例补足。完整解释见 what_is_context.md 与 what_is_mdl.md。

日常只需要记住三条命令

上手之后，你的高频操作基本就这三条：

• wren query --sql '...'：通过 MDL 语义层执行 SQL，支持 table / csv / json 输出；
• wren ask "问题" --guided：把问题包一层结构化提示，交给能力稍弱的 Agent 也能稳定产出；
• wren dry-plan --sql '...'：不连库，直接把 MDL SQL 翻译成目标数据源的方言，改口径前先"空跑"验证，零风险。

所有命令的完整参数在 CLI 参考 里都有，随时可查。

从"拿到答案"到"发出看板"：GenBI 部署一步到位

答案只是开始。当你想让结果变成可分享的东西时，继续对 Agent 说：

"把刚才的结果做成可筛选的交互式看板，部署到我的 Vercel 上。"

Agent 会调用wren skills get genbi加载构建手册，基于你项目的上下文生成一个纯浏览器端运行的看板应用（由 WASM 引擎驱动），本地预览后一条命令发布，最后给你一个公开 URL。支持快照模式（数据打包进应用，适合演示和报表）与实时模式（查看时回连数仓，适合生产场景）。细节见 genbi.md。

接下来往哪走

按这个顺序深入，每一步都有对应文档：

1. 连接你自己的数据库：profile 机制、各数据源支持的字段，见 connect.md；连接器源码在 core/wren/src/wren/connector/，覆盖 22+ 数据源；
2. 用完整样例跑一遍：快速上手指南 用 jaffle_shop 演示从建库到问数的每一步；
3. 接入更多 Agent：wren serve mcp可以把查询、schema 和业务知识的工具暴露给任意 MCP 客户端，指南见 mcp.md；
4. 写代码集成：LangChain 与 Pydantic 参考 SDK 分别位于 sdk/wren-langchain/ 和 sdk/wren-pydantic/；
5. 看一个真实项目长什么样：完整示例工程在 examples/v5-jaffle/，模型、视图、关系、知识文件一应俱全。

你不需要会写复杂 SQL，也不需要维护一套新系统——装好 CLI、连上数据库、用自然语言提问，WrenAI 就把"问数—验证—可视化—分享"这条链路交到了你和你的 AI Agent 手里。先从今天那条"问一个问题"的路径开始吧。

【免费下载链接】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