Query Builder
Query Builder 帮助用户创建结构化数据查询,无需手写原始 SQL。当查询需要被 Dashboard、Report、页面或 agent 工具复用时,它尤其有用。
为什么使用 Query Builder
业务应用经常需要可重复的提问:
- 按来源与状态的 lead
- 按区域与月份的订单
- 超过阈值的待审批任务
- 按客户分群的收入
- 缺少必需运营数据的记录
与其把这些编码进自定义组件,不如把查询定义为元数据并加以复用。
查询形态
查询定义通常包含:
| 部分 | 用途 |
|---|---|
| 基础 Model 或表 | 主数据源 |
| 选中字段 | 返回给调用方的列 |
| 筛选 | 静态或参数化的约束 |
| 排序 | 默认排序 |
| 分组 | 用于聚合的维度 |
| 指标 | count、sum、avg、min、max |
| 参数 | runtime 输入,例如时间区间或负责人 |
Query Builder 应让这些选择显式化,以便查询能被安全地校验和复用。
参数
参数化查询比硬编码筛选更安全、更可复用。
| 参数 | 示例 |
|---|---|
fromDate | 报表周期起始 |
toDate | 报表周期结束 |
ownerId | 当前用户或所选负责人 |
status | 选中的流程状态 |
tenantId | 当前 Tenant 范围 |
Dashboard 与 Report 可将 UI 筛选项绑定到这些参数。
消费方
| 消费方 | 如何使用查询 |
|---|---|
| Dashboard Designer | 图表与 KPI 的数据源 |
| Report Designer | 表格、交叉表与汇总 Block |
| Page Designer | 已保存的视图或基于筛选的区段 |
| Aura Bot | 用于自然语言分析的只读工具 |
| Plugins | 与元数据打包的可复用数据契约 |
当查询成为 agent 工具的一部分时,请添加清晰的描述与参数示例,让模型知道何时调用它。
安全
Query Builder 不应成为绕过应用权限的旁路。
建议规则:
- 让 Tenant 范围保持显式
- 尽可能优先使用 Model 感知的查询
- 除非必要,避免返回敏感字段
- 在后端应用行级权限规则
- 在发布前评审昂贵的聚合
- 为探索性查询添加 limit
发布检查清单
- 查询名能描述业务问题
- 参数具备标签、类型与默认值
- 已预期并妥善处理空结果
- 已测试 Dashboard / Report 消费方
- 若暴露给 Aura Bot,提供了 agent 使用说明