WrenAI 如何定义 cube 预聚合指标并用 wren cube query 执行结构化查询

WrenAI 如何定义 cube 预聚合指标并用 wren cube query 执行结构化查询【免费下载链接】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在 WrenAI 项目中当你希望把月度收入订单量这类指标从让 AI 每次现写GROUP BYSQL变成一条声明式的结构化接口时需要完成一个具体任务在项目里定义一个 cube预聚合语义对象编译进 MDL 清单然后用wren cube query以 measures / dimensions / time dimension / filter 的结构化参数执行查询。完成后的结果是wren cube list能看到该 cubewren cube query --cube ...直接返回聚合结果不需要手写GROUP BY、DATE_TRUNC或 join 推断。适用前提已经有一个可运行的 Wren 项目即存在已定义的 modelcube 的base_object必须引用一个已定义的 model 或 view、已绑定连接 profile并且之前跑过wren context build生成target/mdl.json。快速上手流程见 Quickstart其中 Step 8 就是添加并查询一个 cube的端到端示例基于 jaffle_shop 的 DuckDBorders表。定义 cube写入cubes/name/metadata.yml每个 cube 位于项目根目录下的cubes/name/metadata.yml。以 quickstart 场景中的ordersmodel 为例文档给出的revenuecube 定义如下YAML 字段一律使用 snake_casename: revenue base_object: orders measures: - name: total expression: SUM(amount) type: DOUBLE - name: order_count expression: COUNT(*) type: BIGINT dimensions: - name: status expression: status type: VARCHAR time_dimensions: - name: order_date expression: order_date type: DATE hierarchies: time: [order_date]各字段的要求以 MDL schema reference 的 Cubes 一节为准字段必填说明name是cube 的唯一名称后续wren cube query --cube用这个名字base_object是cube 聚合所基于的 model 或 view 名schema 中要求必须引用一个已定义的 Model 或 Viewmeasures[]是聚合指标每项包含name、expression、typeJSON Schema 要求至少一个 measuredimensions[]否分类分组维度每项同样需要name、expression、typetime_dimensions[]否时间分组维度。粒度不在这里声明而是在查询时通过--time-dimension name:granularity指定hierarchies否层级名到有序维度名列表的映射用于 drill-down层级中的名字必须匹配dimensions或time_dimensions里已声明的条目refresh_time否缓存刷新间隔properties否任意元数据例如description仓库中有一个可直接参考的真实示例examples/v5-jaffle/cubes/order_metrics/metadata.yml它定义了total_revenueSUM(amount)和order_countCOUNT(*))两个 measure 以及customer_id维度并展示了properties.description的用法。一个常见的结构错误是把时间粒度写进 cube 定义里。time_dimensions只声明列本身如order_dateyear/month/day这类粒度是查询时参数不是 cube 的静态字段。编译并确认 cube 进入 MDLwren cube系列命令读取的是编译产物target/mdl.json可通过--mdl指定其他路径而不是直接读 YAML。所以在写入或修改cubes/*/metadata.yml之后必须重新编译wren context buildwren context build会把 YAML 的 snake_case 字段转换为target/mdl.json中的 camelCase 形式base_object→baseObject、refresh_time→refreshTime等cubes/下的定义会进入清单的cubes数组。验证 cube 是否成功进入清单有两条命令wren cube list wren cube describe revenuewren cube list列出已加载 MDL 中的所有 cube包括每个 cube 的 base 对象、measures、dimensions 和 time dimensions。wren cube describe revenue以 JSON 形式打印该 cube 的完整 schemabaseObject、带表达式的 measures、dimensions、time dimensions 和 hierarchies。cube 不存在时会报错Cube revenue not found.。如果wren cube list报出malformed cubes in mdl.json一类错误文档给出的处理提示是修复cubes/*/metadata.yml中的 cube 定义然后重新运行wren context build。用wren cube query执行结构化查询wren cube query接受结构化输入把 CubeQuery 交给 wren-core 翻译成 SQL生成正确的GROUP BY、DATE_TRUNC和WHERE子句再通过与普通wren --sql相同的路径执行。CLI 参数模式如下wren cube query \ --cube revenue \ --measures total,order_count \ --dimensions status \ --time-dimension order_date:month:2024-01-01,2025-01-01 \ --filter status:eq:completed \ --limit 100关键参数完整列表见 CLI reference 的wren cube一节参数格式 / 说明--cubecube 名称使用--from时可不填--measures逗号分隔的 measure 名使用--from时可不填--dimensions逗号分隔的维度名--time-dimensionname:granularity[:start,end]一个时间维度可附日期范围--filter可重复。dimension:operator[:value]in/not_in的 value 用逗号分隔--limit/--offset分页--from file\|-从 JSON 文件或 stdin 加载 CubeQuery--sql-only只打印生成的 SQL 并退出不执行--mdlMDL JSON 路径默认project/target/mdl.json--outputtable默认、json、csv支持的时间粒度year、quarter、month、week、day、hour、minute。支持的过滤操作符eq、neq、in、not_in、gt、gte、lt、lte、contains、starts_with、is_null、is_not_null。其中is_null/is_not_null不需要 value对应dim:op两段形式其余操作符带 value。quickstart 中查询revenuecube 的最小命令不带 dimensions 和 filterwren cube query \ --cube revenue \ --measures total,order_count \ --time-dimension order_date:month需要再切分时加上--dimensions status或--filter status:eq:completed。先只看 SQL 再执行是文档主路径的验证手段加--sql-only会打印翻译出来的 SQL 并退出不执行、不产生查询开销。确认 SQL 形态符合预期正确的分组、时间截断、过滤条件后再去掉该参数实际执行。JSON 输入模式可选CubeQuery 也可以整体以 JSON 提供从文件读或从 stdin 读--from -cat query.json | wren cube query --from -JSON 就是与 CLI 参数一一对应的 CubeQuery 结构{ cube: revenue, measures: [total, order_count], dimensions: [status], timeDimensions: [ { dimension: order_date, granularity: month, dateRange: [2024-01-01, 2025-01-01] } ], filters: [ { dimension: status, operator: eq, value: completed } ], limit: 100 }timeDimensions中的granularity取值与--time-dimension相同filters中in/not_in的value是列表对应 CLI 的逗号分隔写法。该 JSON 结构按 CLI 参数逐项替换字段名与上文表格一致。什么时候该建 cube什么时候不该Cube guide 给出了明确的分界避免把 cube 当成万能容器适合建 cube 的情况指标被频繁查询revenue、retention、MAU 这类指标有团队一致认可的定义不要为尚未定型的指标建模agent 栈里的小模型或本地模型在聚合 SQL 上容易出错希望有一个能扛住 base model schema 漂移的稳定接口。不要建 cube 的情况指标是探索性或一次性的直接写 SQL 查询即可指标定义还在争论中先写进knowledge/rules/没有清晰的 graincube 需要显式的 measures dimensions。cube 的设计动机也在于此agent 写分析型 SQL 最常见的失败是 join 重建错误、聚合粒度错误导致重复计数、时间粒度歧义导致截断错误、以及发明不符合团队口径的指标——这些在 cube 里都是一次性声明agent 只负责提供结构化输入。执行失败时的检查点文档明确给出的错误与处理方式wren cube query报Error: MDL file not found: pathtarget/mdl.json不存在或未编译先运行wren context build。wren cube list/query报malformed cubes in mdl.jsoncube 定义有结构问题修复cubes/*/metadata.yml后重新wren context build。wren cube describe name报Cube name not found.cube 名与cubes/*/metadata.yml中的name不一致或该 cube 还没编译进清单。--filter/--time-dimension参数格式错误时CLI 会直接给出参数格式说明如--filter expects dim:op[:value]、dateRange must be start,end (exactly two dates)按提示修正格式即可。下一步把 cube 暴露给 MCP 客户端wren serve mcp注册了query_cube、list_cubes、describe_cube工具连接型 agent 可以直接用结构化 cube 查询而不是手写 SQL见 CLI reference 的wren serve一节。把 cube 做成可分享的浏览器端 GenBI 应用quickstart Step 9 展示了基于revenuecube 构建 dashboard 并部署到 Vercel / Cloudflare Pages 的流程。cube 字段的完整定义含hierarchies的 drill-down 语义见 MDL schema reference机器可读的 JSON Schema 在 core/wren-mdl/mdl.schema.json。【免费下载链接】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），仅供参考