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而不是让模型猜 SQLWrenAI 的定位是开源 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 自带依赖项版本要求用途Python3.11运行 wren CLINode.js / npm18用 npx 安装 agent 技能桩AI agent如 Claude Code任一驱动 MDL 生成与日常自然语言查询查询目标数据库PostgreSQL / DuckDB 等DuckDB 随 wrenai 附带无需另装以下路径假设你手头已有一个数据库DuckDB 文件或 Postgres。没有现成库也可用项目内置的 jaffle_shop 示例快速开始文档里有对应流程。创建虚拟环境并安装 CLImemory 附加组件启用记忆索引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 indexwren profile debug时 duckdb 连不上url 指向了 .duckdb 文件本身DuckDB 的 url 应填包含 .duckdb 文件的目录pip install wrenai缓慢或失败国内网络访问 PyPI / HuggingFace 受限为 pip 配置国内镜像源用HF_ENDPOINT环境变量指定 HuggingFace 镜像端点⚠️ 修改任何知识文件或模型定义后都必须重建索引否则召回仍基于旧索引表现为“改了文档但回答没变”。进阶探索系统学习 MDL 语义层的模型、视图、cube 写法读 MDL 概念文档全部 CLI 命令与参数细节见 CLI 参考手册排错时先查这里要把 WrenAI 嵌入自己的 agent 框架看 wren-langchain SDK同目录sdk/下还有同构的wren-pydantic下一步建议从 快速开始文档 的 jaffle_shop 完整流程入手把本文的安装与项目搭建环节实际跑一遍。【免费下载链接】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辅助生成（AIGC），仅供参考
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而不是让模型猜 SQLWrenAI 的定位是开源 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 自带依赖项版本要求用途Python3.11运行 wren CLINode.js / npm18用 npx 安装 agent 技能桩AI agent如 Claude Code任一驱动 MDL 生成与日常自然语言查询查询目标数据库PostgreSQL / DuckDB 等DuckDB 随 wrenai 附带无需另装以下路径假设你手头已有一个数据库DuckDB 文件或 Postgres。没有现成库也可用项目内置的 jaffle_shop 示例快速开始文档里有对应流程。创建虚拟环境并安装 CLImemory 附加组件启用记忆索引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 indexwren profile debug时 duckdb 连不上url 指向了 .duckdb 文件本身DuckDB 的 url 应填包含 .duckdb 文件的目录pip install wrenai缓慢或失败国内网络访问 PyPI / HuggingFace 受限为 pip 配置国内镜像源用HF_ENDPOINT环境变量指定 HuggingFace 镜像端点⚠️ 修改任何知识文件或模型定义后都必须重建索引否则召回仍基于旧索引表现为“改了文档但回答没变”。进阶探索系统学习 MDL 语义层的模型、视图、cube 写法读 MDL 概念文档全部 CLI 命令与参数细节见 CLI 参考手册排错时先查这里要把 WrenAI 嵌入自己的 agent 框架看 wren-langchain SDK同目录sdk/下还有同构的wren-pydantic下一步建议从 快速开始文档 的 jaffle_shop 完整流程入手把本文的安装与项目搭建环节实际跑一遍。【免费下载链接】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辅助生成（AIGC），仅供参考