Data Engineering Agent 指标规范设计指南

指标规范设计是数据工程进入建模和开发前的重要步骤。它把字段、业务口径、统计粒度、时间口径和命名规范先梳理清楚，避免后续任务开发、数仓建模、看板建设和数据分析中出现口径不一致。

Data Engineering Agent 可以基于表结构、样例数据和业务目标，帮助识别字段角色、设计指标口径、发现口径风险，并给出后续沉淀到数仓或语义层的建议。

适用场景

以下场景适合先做指标规范设计：

接手一张陌生业务表，需要判断哪些字段适合做维度、指标和过滤条件
准备建设销售、运营、客户、商品、财务等主题指标
多个字段含义相似，容易造成统计口径误用
准备搭建 DWD / DWS / ADS 或 Silver / Gold 分层模型
准备把指标沉淀到 BI、语义层或分析应用中
业务团队对同一个指标有不同理解，需要先形成统一口径

不要在字段含义和指标口径都不清楚时直接要求 Agent 创建任务。先完成指标规范设计，可以减少返工和错误数据产出。

推荐工作流

先做只读探查

让 Agent 先查看表结构和少量样例数据，不创建任务、不写入表、不修改配置。

推荐提问：

请基于

{schema}.{table}

{schema}.{table}

做一次指标规范设计。先只做只读探查，查看表结构和少量样例数据；不要创建任务，不要写入表，不要修改配置。

Agent 通常会关注：

字段名和字段类型
是否存在主键或订单行 ID
哪些字段适合做维度
哪些字段适合做度量
哪些字段适合做时间口径
哪些字段更像系统字段或审计字段
样例数据中的空值、异常值、日期范围和枚举值

识别字段角色

指标规范设计的第一步是明确字段角色。

字段角色	含义	示例
维度字段	用于分组、切片和对比	商品、客户、地区、渠道
指标字段	用于求和、计数、平均、占比等计算	金额、数量、时长、成本
时间字段	用于按日、周、月、季度统计	销售日期、下单时间、分区日期
过滤字段	用于限定业务范围	状态、类型、是否有效、是否退款
系统字段	用于数据治理或技术追踪	创建时间、更新时间、批次号

对于时间字段，要区分业务发生时间和系统处理时间。例如销售分析通常使用销售日期，而不是数据写入时间。

设计指标口径

让 Agent 输出指标定义时，应至少包含以下信息：

指标名称
业务定义
计算逻辑
数据源
统计粒度
可用维度
时间口径
过滤条件
口径风险

示例指标：

指标	业务定义	常见计算逻辑
销售额	指定时间范围内有效订单的销售金额	`SUM(sale_amount)` SUM(sale_amount)
订单数	指定时间范围内的订单数量	`COUNT(order_id)` COUNT(order_id) 或 `COUNT(DISTINCT order_id)` COUNT(DISTINCT order_id)
客单价	平均每个订单或客户的消费金额	`SUM(amount) / COUNT(DISTINCT order_id)` SUM(amount) / COUNT(DISTINCT order_id)
商品销售排行	按商品汇总销售额并排序	`SUM(amount) GROUP BY product_name` SUM(amount) GROUP BY product_name
日均销售额	时间范围内平均每日销售额	`SUM(amount) / COUNT(DISTINCT sale_date)` SUM(amount) / COUNT(DISTINCT sale_date)

订单数和客单价尤其需要业务确认。如果表中只有订单行 ID，没有订单头 ID，

COUNT(*)

COUNT(*)

可能统计的是订单行数，而不是订单数。

口径风险检查

指标规范设计不能只输出指标列表，还要暴露口径风险。

常见风险包括：

金额字段不清楚是实付金额、原价、含税金额还是退款后净额
缺少订单状态、退款标识、有效标识，无法判断哪些记录应计入指标
```
created_at
```
created_at
、
```
updated_at
```
updated_at
、
```
biz_date
```
biz_date
、
```
sale_date
```
sale_date
等时间字段混用
ID 字段可能是订单行 ID，而不是订单 ID
同一个表中存在多个相似金额字段或日期字段
样例数据太少，无法判断枚举值、空值和异常值
指标按客户、订单、商品、门店等不同粒度统计时口径不同

推荐提问：

请指出这些指标中最容易产生口径歧义的地方，包括金额字段、时间字段、ID 字段、状态字段和统计粒度。请给出需要业务确认的问题清单。

指标命名建议

指标命名应稳定、可读、可维护。建议使用统一命名规则，例如：

{业务域}_{指标含义}_{统计方式}

示例：

指标	建议命名	说明
总销售额	`sales_amount_total` sales_amount_total	销售金额求和
订单数	`sales_order_count` sales_order_count	订单数量
客单价	`sales_avg_order_value` sales_avg_order_value	平均订单价值
商品销售排行	`sales_product_rank` sales_product_rank	商品维度排行
客户订单数	`sales_customer_order_count` sales_customer_order_count	客户维度订单数量

如果企业已有指标命名规范，应让 Agent 按现有规范输出，而不是重新发明一套命名。

沉淀到数仓和语义层

指标规范设计完成后，可以继续进入建模和开发。

常见沉淀方式：

在 DWD 或 Silver 层保留清洗后的明细数据
在 DWS 或 Gold 层按日、商品、客户、渠道等维度做预聚合
在 ADS 层产出面向看板或应用的宽表
在语义层中注册度量、维度、时间字段和业务说明
在知识库或指标目录中沉淀指标定义、适用场景和例外规则

推荐提问：

请基于这份指标规范，设计 DWD / DWS / ADS 三层模型。先输出每层目标、输入表、输出表、字段处理逻辑和指标口径，不要创建任务。

Data Engineering Agent 指标规范设计指南

适用场景

推荐工作流

先做只读探查

识别字段角色

设计指标口径

口径风险检查

指标命名建议

沉淀到数仓和语义层

推荐提问模板

生成指标规范

检查口径风险

生成指标需求文档

进入数仓建模

相关文档