业务口径与指标
维护业务资料、查询口径和指标,按需配置期间、层级和对数基准。
业务资料与查询口径
业务资料
打开「业务维护 › 业务定义 › 业务资料」,有两种方式补充业务含义:
- 文字说明:在「补充说明」里写字段解释、状态枚举、统计口径和业务例外,点「保存说明」。例如「orders 中的 customer_id 关联 customers 的 id,订单金额不包含已退款部分」。
- 说明文档:点「上传说明文档」。支持 TXT、Markdown、CSV、JSON、PDF 和 DOCX,单个文件不超过 2 MiB,PDF 最多 200 个文本页,扫描版需要先转成文字。上传时即提取正文,读取失败时页面会说明原因,该文件不会保存。
说明文档本身也是授权资源。Agent 只能使用被授权读取的文档。每个数据源最多 100 份说明文档(含查询口径)。
查询口径
查询口径是核对过的 SQL 加统计口径,给 AI 作参考。打开「业务维护 › 业务定义 › 查询口径」,点「新增查询」。每个数据源最多 50 条查询口径。
| 字段 | 说明 |
|---|---|
| 查询名称 | 例如「已支付订单收入」。 |
| 对应的业务问题 | 这条 SQL 回答什么问题。 |
| 业务口径与适用范围 | 例如「仅统计已支付订单,收入按商品数量乘成交价汇总」。 |
| 只读 SQL | 保存时校验,不执行。 |
保存后是「草稿」。保存时数脉校验 SQL 只用到当前授权的表、字段和已确认的完整关联。点「人工确认」后状态变为「已确认」,才进入 AI 问数的业务依据。编辑会撤回确认;表结构、关联或授权变化后,数脉会重新校验,不满足时状态变为「需重新确认」,这条样例就不再进入 AI 上下文,需要检查、编辑后重新确认。「填入调试」会把它的业务问题填进调试页的测试用例,不会自动执行。
指标定义与发布
指标口径是按数据源维护的官方指标定义。打开「业务维护 › 业务定义 › 指标口径」,点「新增指标」。
| 字段 | 说明 |
|---|---|
| 指标名称、业务说明 | 必填。名称在数据源内唯一,每个数据源最多 200 个指标。说明里写统计口径、包含与排除的情况和单位。 |
| 别名(可选) | 用逗号或顿号分隔,例如「销售额、GMV」。 |
| 负责人 | 必填,例如「数据组 · 张三」。 |
| 适用表 | 1 到 5 张,第一张是主表。 |
| 默认时间字段、默认时间粒度 | 可选。粒度有按日、按周、按月、按季度、按年。 |
| 计算表达式 | 一个 SQL 表达式,用别名 t 引用适用表的字段,例如 SUM(CASE WHEN t.status = 'paid' THEN t.amount ELSE 0 END)。保存时对每张适用表校验:只允许单个输出、只引用该表、不含分号或注释。 |
| 结构化口径(可选) | 写明聚合方式(求和、计数、去重计数、平均、最小值、最大值、比率)、度量字段、过滤条件、空值处理、单位、小数位、舍入方式和可加性。比率要选分子和分母指标,并说明分母为零时记为空还是 0。还可以设置统计期间、快照取值和币种折算。 |
点「校验并保存」,指标先是「草稿」。管理员点「确认指标」后才是「已确认」,已确认的指标才会作为 AI 问数的口径参考,也才会出现在 Agent 的指标列表里。任何修改都会让指标回到草稿,需要重新确认。「停用」后不再提供给 AI,已确认的指标需要先停用才能删除。
两点要记住:
- 指标口径只是业务指引,不授予任何表、字段或关联的权限,生成的 SQL 仍然完整校验。指标只对能读取它全部相关表和字段的身份可见。
- 参考口径条目和可执行的结构化指标用途不同。只有已确认且带结构化口径的指标,才能用来建模板查询;对数基准也依赖结构化指标。没有结构化口径时,指标仍作问数参考,但不能用于模板。
修改、重新确认、停用或删除指标,会把用到该指标的模板查询标记为待复核,指标的任何修改都算,包括只改说明。重新采集后结构有变化、修改关系,也会把受影响的常用查询标记为待复核。只改表或字段的业务说明不会触发复核。
业务口径与数据版本
财务类和需要按会计期间统计的指标,要用到下面几项配置。不做这类统计时可以跳过。在手册里这几项统称「业务口径」,现在分在面板的几个标签里。
| 配置 | 位置 | 要点 |
|---|---|---|
| 期间日历 | 「数仓(数脉) › 业务定义 › 期间日历」 | 数据源级。填日历编号、名称,可按年度和起始月份生成期间,也可粘贴或导入 CSV,还可以「从源库期间表读取」:选期间表和各字段,用数据源的只读账号读,最多 500 行,预览后采用,保存后可在日历列表里「从期间表刷新」。每个期间有期间键(与源库期间字段里的值一致,如 2026-09)、年度、季度、开始和结束日期,可标为调整期(如第 13 期)。每个数据源最多 20 个日历,每个日历最多 600 个期间,跨度不超过 50 年,常规期间不能重叠。 |
| 编码层级 | 「数仓(数脉) › 业务定义 › 编码层级」 | 登记科目或组织的上下级结构:所在表、编码字段、名称字段,下级规则选「按上级编码字段」或「按编码前缀」,再导入节点。每个数据源最多 20 个层级,最多 5000 个节点。指标过滤用「属于子树」引用层级编号,含全部下级。 |
| 对数基准 | 「数仓(数脉) › 业务定义 › 对数基准」 | 一条标准答案:选结构化指标、期间或日期范围和过滤条件,填期望值、允许误差、出处和负责人,选「阻断」或「只告警」,可设每日运行。每个数据源最多 100 条,保存后立即运行一次。读取的期间全部已关账且选了「阻断」时,未通过会让指标进入待复核,基于它的模板查询不能新建也不能运行。 |
| 期间状态与数据版本 | 「数仓管理 › 证据留存」 | 两条只读查询。期间状态查询返回期间键和状态两列,数据版本查询取第一行第一列(例如 ETL 批次号)。保存时经只读 SQL 校验,由该数据源的只读账号执行,结果缓存 60 秒,最多读 500 行。点「立即检查」验证。未配置时,结果依据里的期间状态记为「未知」,不会推断。 |
期间状态的取值:closed、已关账、已结账、Y、yes、1、true 记为已关账;open、未关账、未结账、N、no、0、false 记为未关账;其他取值和没有列出的期间都记为状态未知。
配置完成后,用对应的模板查询和对数基准验证期间、层级和基准是否生效。期间、科目和差异容差应由业务负责人确认,并按业务周期复核。