WrenAI 如何用 jaffle_shop 样例数据集和 Claude Code 完成首个 text-to-SQL 查询【免费下载链接】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本文的目标是完成一次完整的 Wren AI 首次上手使用 dbt Labs 公开的jaffle_shop样例数据集DuckDB 本地库无需云数据库或 Docker在Claude Code中用自然语言提问让 Wren AI 通过其上下文层生成并执行 SQL。整个流程约 15 分钟最终你会得到一个本地上下文层加记忆系统AI agent 靠它理解数据含义而不是只凭表结构猜。开始前先熟悉三个术语后文会反复出现Wren CLIwrenPython 命令行工具连接数据库、管理模型文件、通过上下文层执行 SQL、维护本地记忆索引MDLModeling Definition Languagemodels/、views/、relationships.yml下的 YAML 文件用业务语言描述表、列和关联。agent 读的是 MDL不是裸 schemaSkillsmarkdown 工作流指南告诉 AI coding agent 如何操作 Wren CLI。本流程用到其中两个generate-mdl一次性脚手架和usage日常查询。准备条件按 快速开始文档 的要求需要Claude Code已安装并完成认证Python 3.11Node.js / npm如果用npx安装 skill 时需要Git。先创建并激活虚拟环境把 dbt 和 wrenai 的依赖与系统 Python 隔离开。之后每个新终端会话里运行dbt或wren命令前都要先激活它python3 -m venv ~/.venvs/wren source ~/.venvs/wren/bin/activate生成 jaffle_shop 数据集克隆 dbt 的 jaffle_shop DuckDB 项目并构建数据库git clone https://github.com/dbt-labs/jaffle_shop_duckdb.git cd jaffle_shop_duckdb pip install dbt-core dbt-duckdb dbt build验证数据库文件已生成ls jaffle_shop.duckdbdbt build会先生成三张原始种子表再构建三个 staging 视图和两张分析表对象名称分析表建模对象customers、ordersstaging 视图stg_customers、stg_orders、stg_payments原始种子raw_customers、raw_orders、raw_payments快速开始只需customers和orders两张表。raw_*和stg_*是 dbt 的中间层要把它们排除在 Wren 项目之外让 agent 对每个概念只看到一张无歧义的表。记下该目录的绝对路径配置 profile 时要用pwd安装 wrenai 包本场景使用 DuckDB 记忆 UI 交互式提示安装命令pip install wrenai[memory,main]DuckDB 连接器默认包含无需额外 extras。如果要连接其他数据源追加对应连接器例如pip install wrenai[memory,main,postgres]。可用的连接器 extras 包括postgres、mysql、bigquery、snowflake、clickhouse、trino、mssql、databricks、redshift、athena、oracle、sparkmemory提供基于 LanceDB 的语义记忆main提供交互式提示和浏览器 profile UI。验证安装wren version安装 CLI skillSkills 是教 AI coding agent 使用 Wren CLI 的工作流指南。安装 discovery stub它会在运行时按需从 CLI 拉取具体指南npx skills add Canner/WrenAI安装器会自动检测已装的 agent如果同时装了多个 agent用--agent name指定例如--agent claude-code。也可以改用仓库自带的本地脚本bash skills/install.sh见 skills 说明。安装后只有一个 skillwrenClaude Code 下位于~/.claude/skills/wren/SKILL.md工作流指南通过wren skills get name按需获取。本流程用到指南用途usage日常查询收集上下文、召回历史查询、写 SQL、存储结果generate-mdl一次性设置探索数据库结构并生成 MDL 项目创建并验证 profileprofile 存储数据库连接信息类似 dbt profiles。针对 jaffle_shop 的 DuckDB 数据库有三种创建方式任选其一。以下命令中的/Users/you/jaffle_shop_duckdb都是目录存放.duckdb文件的目录不是.duckdb文件本身替换为上一节pwd的输出方式 A浏览器 UI文档推荐wren profile add jaffle-shop --ui打开的表单中填写Data source 选duckdbDatabase path 填项目目录的绝对路径。方式 B交互式 CLIwren profile add jaffle-shop --interactive方式 C从 YAML 文件导入。创建jaffle-profile.ymldatasource: duckdb url: /Users/you/jaffle_shop_duckdb format: duckdbwren profile add jaffle-shop --from-file jaffle-profile.yml验证 profile 已生效并测试连接wren profile list wren profile debugwren profile list中应看到jaffle-shop标记为 activewren profile debug用来验证连接可用。初始化 Wren 项目并绑定 profile创建项目目录并搭建结构mkdir -p ~/jaffle-wren cd ~/jaffle-wren wren context init会生成wren_project.yml项目元数据、models/、views/、cubes/、relationships.yml和knowledge/业务规则与 NL→SQL 对。注意wren_project.yml里的catalog和schema是 Wren AI 自己的命名空间与数据库的 catalog/schema 无关保持默认wren/public即可每张表在数据库中的实际位置在各自的table_reference里指定。然后把这个项目绑定到刚创建的 profilewren context set-profile jaffle-shop这会把profile: jaffle-shop和data_source: duckdb写进wren_project.yml之后无论全局激活的是哪个 profile这个项目的查询都会走绑定连接。用 Claude Code 生成 MDLwren context init创建了一个示例 model 和 view它们是占位符需要删除副作用说明此命令只会删除刚生成的models/example_model和views/example_view两个占位目录不涉及其他文件rm -rf models/example_model views/example_view在项目目录中打开 Claude Codecd ~/jaffle-wren claude然后提出建模请求Use the /wren skill to explore the jaffle_shop database and generate the MDL for the customers and orders tables. Skip the raw_* seeds and stg_* views. The data source is DuckDB.wrenskill 会把这识别为脚手架任务拉取generate-mdl指南wren skills get generate-mdl来驱动整个流程。Claude Code 会依次发现customers和orders表内省列与类型SQLAlchemy 或information_schema用wren utils parse-type归一化类型在models/下每表写一个 YAML根据外键和命名约定推断关系向你索要关键表/列的描述执行wren context validate和wren context build校验并构建最后执行wren memory index生成种子 NL-SQL 示例。macOS 用户注意首次wren memory命令加载的原生库lancedb、torch约 800MB会触发一次性的 XProtect 安全扫描可能看起来像卡住几十秒。这是一次性的正常行为不是故障如果不想在演示中途等待可以装好后先单独跑一次wren memory命令让它完成。完成后验证项目wren context show wren memory status提出第一个自然语言问题在项目目录的 Claude Code 中直接用自然语言提问How many customers placed more than one order?Which 5 customers have the highest lifetime value?Show me the monthly order count trend.Claude Code 会按usage指南走完整链路wren memory fetch检索与问题相关的表和列 →wren memory recall召回相似的历史查询 → 基于上下文层用模型名而非裸表名写 SQL →wren --sql ...通过 Wren 引擎执行 →wren memory store把成功的 NL-SQL 对存下来供以后召回。每存一次后续召回就更准。如果需要脱离 agent 手动核对文档给出的常用命令包括wren --sql SELECT ... -o table执行 SQL、wren dry-plan --sql SELECT ...预览计划 SQL、wren dry-run --sql SELECT ...校验 SQL、wren memory status查看记忆状态。可选后续与限制文档把 cube预聚合指标对象和 GenBI 仪表盘列为可选步骤generate-mdl只搭表和关系不生成 cube如需聚合指标可以在 Claude Code 中让 agent 按revenuecube 的示例描述添加再用wren cube query查询GenBI 则能把结果构建成可部署到 Vercel 或 Cloudflare Pages 的浏览器端应用这些超出“首个查询”的范围本文不展开。两个边界条件本快速开始只建模customers和orders中间层对象要主动跳过编辑knowledge/rules/、models/*/metadata.yml或relationships.yml后需要依次重新执行wren context validate、wren context build、wren memory index才能让改动生效。如果你想用自己的数据库而不是 jaffle_shop完成安装步骤后跳转到 Connect your database完整路径的 快速开始文档 中还提供了逐步带截图式的补充说明。【免费下载链接】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），仅供参考