大数据智能体工作台 DataBuddy 质量规则配置指南

概述
数据质量规则用于对数据表和字段进行自动化质量检测。通过配置规则，系统可以自动监控数据的完整性、准确性、唯一性、一致性、有效性和及时性，并在检测值满足触发条件时产生异常告警。
配置文件支持以下能力：
支持 系统模板（system_template）和 自定义 SQL（custom_sql）两种规则类型。
支持 表级规则（table_rules）和 字段级规则（field_rules）两种规则级别。
可在一个配置文件中定义 多条规则，灵活组合。
核心概念
规则类型
规则类型
标识
说明
系统模板
system_template
使用系统内置的检测模板，只需指定 template_code 即可。系统模板已内置质量维度，用户无需指定 dimension。
自定义 SQL
custom_sql
用户编写自定义 SQL 查询语句，灵活实现各种检测逻辑。需要用户指定 dimension（质量维度）和 custom_sql（SQL 语句）。
规则级别
规则级别
配置节点
说明
表级规则
table_rules
针对整张表进行检测，如行数检查、数据产出及时性检查等。
字段级规则
field_rules
针对表中的某个具体字段进行检测，如空值率、重复值、平均值等。需额外指定 field_name。
质量维度
质量维度用于对规则进行分类，仅在 custom_sql 类型下需要指定（系统模板已内置）。
维度标识
中文名
说明
completeness
完整性
检测数据是否存在缺失
accuracy
准确性
检测数据值是否在合理范围内
validity
有效性
检测数据格式、类型是否合规
uniqueness
唯一性
检测数据是否存在重复
consistency
一致性
检测不同数据源或表之间数据是否一致
timeliness
及时性
检测数据是否按时产出
系统模板参考
表级模板
模板标识
名称
说明
trigger_condition
table_row_count
表行数
检测表的总行数是否在合理范围内
用户自定义
data_timeliness
数据产出及时性
检测数据是否按时产出
系统固定无需填写。通过 filter 配置业务过滤条件
字段级模板
模板标识
名称
说明
trigger_condition
null_count
字段空值个数
统计字段中空值的个数
用户自定义
null_rate
字段空值率
统计字段中空值占比
用户自定义
not_null_count
字段非空计数
统计字段中非空值的个数
用户自定义
duplicate_count
字段重复值个数
统计字段中存在重复的值的个数
用户自定义
distinct_count
字段去重计数
统计字段中不同值的个数
用户自定义
min_value
字段最小值
获取字段的最小值
用户自定义
max_value
字段最大值
获取字段的最大值
用户自定义
sum_value
字段求和
计算字段的总和
用户自定义
avg_value
字段平均值
计算字段的平均值
用户自定义
median_value
字段中位数
计算字段的中位数
用户自定义
std_dev
字段标准差
计算字段的标准差
用户自定义
enum_range_consistency
枚举范围一致性
检测字段值是否在合法枚举范围内
系统固定无需填写。通过 params.enum_values 配置合法枚举值列表
触发条件表达式语法
trigger_condition 描述的是检测值应满足什么条件时触发异常。
核心语义：满足 trigger_condition 则触发异常。
简单比较
使用比较运算符直接与目标值进行比较。
支持的运算符：
运算符
含义
==
等于
!=
不等于
 >
大于 |
<
小于
=
大于等于 |
<=
小于等于
示例：
trigger_condition: "> 100"  # 检测值大于 100 则触发
trigger_condition: "<= 0"   # 检测值小于等于 0 则触发
trigger_condition: "== 24"  # 检测值等于 24 则触发
trigger_condition: "!= 0"   # 检测值不等于 0 则触发
trigger_condition: "> 0"    # 检测值大于 0 则触发
﻿
区间表达式
用于检查检测值是否在或不在某个数值区间内。
语法格式： between 或 not_between 加 左括号下界逗号上界右括号
括号说明：
括号
含义
[ 或 ]
包含边界值（闭区间）
( 或 )
不包含边界值（开区间）
表达式说明：
表达式
含义
触发时机
between [0,150]
值落在 0到150 内
值在区间内时触发
between (0,100)
值落在 0到100 内
值在区间内时触发（不含边界）
between [0,100)
值落在 0到100 内
值在区间内时触发（含左不含右）
between (0,100]
值落在 0到100 内
值在区间内时触发（不含左含右）
not_between [0,100]
值不在 0到100 内
值超出区间时触发
not_between (0,100)
值不在 0到100 内
值超出区间时触发
实际场景中多使用 not_between，表达检测值超出正常范围则触发异常。
示例：
﻿
trigger_condition: "not_between [1000,1000000]"   
# 表行数不在此范围内则触发
trigger_condition: "not_between [10, 10000]"      
# 字段均值不在此范围内则触发
trigger_condition: "not_between [1, 50]"          
# 去重计数不在此范围内则触发
﻿
组合条件
支持使用 AND（同时满足）和 OR（满足任一）连接多个条件。
连接词
含义
AND
所有条件同时满足时触发
OR
任一条件满足时触发
示例：
选项一
﻿
trigger_condition: "< 100 OR > 1000000"  # 行数过少或过多均触发
trigger_condition: "> 100 AND < 200"     # 值大于100且小于200时触发
注意：
between 和 not_between 表达式中的区间不会被误拆为多个条件。
自定义 SQL 字段名前缀
当规则类型为 custom_sql 时，trigger_condition 中的每个条件必须带字段名前缀，字段名须与 SQL 返回的列名一致。
示例：
选项一
﻿
trigger_condition: "check_value > 0"                
# SQL返回列名为check_value
trigger_condition: "null_count == 0"                         
# SQL返回列名为null_count
trigger_condition: "check_value > 0 AND total_count >= 100"  
# 多列组合判断
trigger_condition: "check_value not_between [0, 100]"        
# 区间也支持
模板与触发条件兼容性约束
不同模板对 trigger_condition 的配置要求不同，请严格遵循以下约束。
模板或类型
trigger_condition 配置方式
补充说明
普通系统模板（如 table_row_count、null_rate、avg_value 等）
用户自定义。支持简单比较、区间、组合条件
无
data_timeliness 模板
无需填写，触发条件由系统固定
通过 filter 字段配置业务过滤逻辑
enum_range_consistency 模板
无需填写，触发条件由系统固定
通过 params.enum_values 配置合法枚举值列表
自定义 SQL
用户自定义。支持带字段名前缀的所有表达式格式
trigger_condition 中的字段名须与 SQL 返回的列名一致
配置字段说明
通用字段
字段
类型
必填
说明
rule_name
string
是
规则名称，建议使用描述性名称
rule_type
string
是
规则类型：system_template 或 custom_sql
trigger_condition
string
视模板而定
触发条件表达式（部分模板由系统固定，无需填写）
filter
string
否
可选，附加 WHERE 过滤条件
系统模板专用字段
字段
类型
必填
说明
template_code
string
是
系统模板标识，通过 DescribeRuleTemplates 接口查询
params
object
否
部分模板需要的额外参数
自定义 SQL 专用字段
字段
类型
必填
说明
custom_sql
string
是
自定义 SQL 查询语句
dimension
string
是
质量维度：completeness、accuracy、validity、uniqueness、consistency、timeliness
字段级规则专用字段
字段
类型
必填
说明
field_name
string
是
目标检测字段名称
配置示例
表级规则示例
示例 1：表行数范围检查（系统模板）
选项一
table_rules:
  - rule_name: 表行数范围检查
    rule_type: system_template
    template_code: table_row_count
    trigger_condition: not_between [1000,1000000]
    filter: status != DELETED
说明：
使用 table_row_count 模板检测表行数，当行数不在 1000 到 1000000 之间时触发中等告警，并通过 filter 排除已删除数据。
示例 2：表行数组合条件检查（系统模板）
选项一
table_rules:
  - rule_name: 表行数异常检查
    rule_type: system_template
    template_code: table_row_count
    trigger_condition: < 100 OR > 1000000
﻿
示例 3：数据产出及时性检查（系统模板 - 固定触发）
选项一
table_rules:
  - rule_name: 数据产出及时性检查
    rule_type: system_template
    template_code: data_timeliness
    filter: update_time >= DATE_SUB(NOW(), INTERVAL 2 HOUR)
示例 4：跨表数据一致性检查（自定义 SQL）
选项一
table_rules:
  - rule_name: 订单金额一致性检查
    rule_type: custom_sql
    dimension: consistency
    custom_sql: >﻿
      SELECT ABS(
        (SELECT SUM(order_amount) FROM order_table WHERE dt = 20260101)
        - (SELECT SUM(detail_amount) FROM order_detail_table WHERE dt = 20260101)
      ) as check_value FROM dual
    trigger_condition: check_value != 0
﻿
说明：
自定义 SQL 计算两张表的金额差值，当差值不为 0 时说明金额不一致，触发告警。注意 trigger_condition 中的 check_value 需与 SQL 返回的列名一致。
字段级规则示例
示例 1：字段空值率检查。
对 user_id 字段进行空值率检查，作为必填字段不允许出现任何空值。
选项一
field_rules:
  - field_name: user_id
    rule_name: 用户ID空值率检查
    rule_type: system_template
    template_code: null_rate
    trigger_condition: "> 0"
示例 2：字段重复值检查
对 order_id 字段进行唯一性检查，不允许出现重复的订单 ID。
选项一
field_rules:
  - field_name: order_id
    rule_name: 订单ID重复值检查
    rule_type: system_template
    template_code: duplicate_count
    trigger_condition: "> 0"
示例 3：字段平均值范围检查
检测 order_amount 字段的平均值是否在 10 到 10000 的合理区间内。
选项一
field_rules:
  - field_name: order_amount
    rule_name: 订单金额均值检查
    rule_type: system_template
    template_code: avg_value
    trigger_condition: not_between [10, 10000]
﻿
示例 4：自定义 SQL - 字段格式校验
选项一
﻿
field_rules:
  - field_name: phone_number
    rule_name: 手机号格式校验
    rule_type: custom_sql
    dimension: validity
    custom_sql: 
      SELECT COUNT(*) as check_value
      FROM user_info_table WHERE dt = 20260101
      AND phone_number IS NOT NULL
      AND phone_number NOT REGEXP 1[3-9][0-9]{9}
    trigger_condition: check_value > 0
﻿
示例 5：枚举值范围一致性校验（系统模板 - 固定触发）
选项一
field_rules:
  - field_name: gender
    rule_name: 性别枚举值范围一致性校验
    rule_type: system_template
    template_code: enum_range_consistency
    params:
     enum_values: M,F,Unknown
常见问题 FAQ
Q1：系统模板和自定义 SQL 如何选择？
建议优先使用系统模板，简洁高效且无需指定质量维度；当模板无法满足需求时，再使用自定义 SQL。
场景
推荐类型
标准的字段统计检查（空值率、重复值、均值等）
system_template
跨表数据一致性比对
custom_sql
复杂业务逻辑校验（格式、范围、关联检查等）
custom_sql
简单的表行数或及时性检查
system_template
Q2：trigger_condition 什么时候不需要填写？
以下两种模板的触发条件由系统固定，无需填写 trigger_condition：
data_timeliness（数据产出及时性）：通过 filter 配置业务过滤条件。
enum_range_consistency（枚举范围一致性）：通过 params.enum_values 配置合法枚举值。
Q3：自定义 SQL 中 trigger_condition 的字段名有什么要求？
trigger_condition 中引用的字段名必须与自定义 SQL 返回结果集中的列名完全一致。
例如 SQL 返回 check_value 列，则条件应写为 check_value > 0，而不能写成 > 0。
Q4：between 和 not_between 有什么区别？
between [a, b]：值在区间内时触发异常（较少使用）
not_between [a, b]：值不在区间内时触发异常（常用，表示超出正常范围）
实际业务中，大多数场景使用 not_between，表达检测值超出正常范围时触发告警。
Q5：filter 字段的作用是什么？
filter 是一个可选字段，用于在检测时附加 WHERE 过滤条件，限制参与检测的数据范围。
常见用途：
排除已删除或无效数据。
限定特定分区或地区的数据。
配合 data_timeliness 模板限定时间范围。
Q6：如何获取可用的系统模板列表？
通过调用 DescribeRuleTemplates 接口查询当前系统支持的所有模板信息，包括模板标识（template_code）、适用级别（表级或字段级）、内置质量维度等。
Q7：一个配置文件中可以定义多少条规则？
没有数量限制。可以在同一个配置文件中自由组合表级规则和字段级规则，系统将逐条执行检测。
Q8：dimension 字段什么时候需要填写？
系统模板（system_template）：不需要，系统已内置质量维度。
自定义 SQL（custom_sql）：必须填写，从 completeness、accuracy、validity、uniqueness、consistency、timeliness 中选择。
﻿

规则类型	标识	说明
系统模板	system_template	使用系统内置的检测模板，只需指定 template_code 即可。系统模板已内置质量维度，用户无需指定 dimension。
自定义 SQL	custom_sql	用户编写自定义 SQL 查询语句，灵活实现各种检测逻辑。需要用户指定 dimension（质量维度）和 custom_sql（SQL 语句）。

规则级别	配置节点	说明
表级规则	table_rules	针对整张表进行检测，如行数检查、数据产出及时性检查等。
字段级规则	field_rules	针对表中的某个具体字段进行检测，如空值率、重复值、平均值等。需额外指定 field_name。

维度标识	中文名	说明
completeness	完整性	检测数据是否存在缺失
accuracy	准确性	检测数据值是否在合理范围内
validity	有效性	检测数据格式、类型是否合规
uniqueness	唯一性	检测数据是否存在重复
consistency	一致性	检测不同数据源或表之间数据是否一致
timeliness	及时性	检测数据是否按时产出

模板标识	名称	说明	trigger_condition
table_row_count	表行数	检测表的总行数是否在合理范围内	用户自定义
data_timeliness	数据产出及时性	检测数据是否按时产出	系统固定无需填写。通过 filter 配置业务过滤条件

运算符	含义
==	等于
!=	不等于
>	大于 \|
<	小于
=	大于等于 \|
<=	小于等于

括号	含义
[ 或 ]	包含边界值（闭区间）
( 或 )	不包含边界值（开区间）

表达式	含义	触发时机
between [0,150]	值落在 0到150 内	值在区间内时触发
between (0,100)	值落在 0到100 内	值在区间内时触发（不含边界）
between [0,100)	值落在 0到100 内	值在区间内时触发（含左不含右）
between (0,100]	值落在 0到100 内	值在区间内时触发（不含左含右）
not_between [0,100]	值不在 0到100 内	值超出区间时触发
not_between (0,100)	值不在 0到100 内	值超出区间时触发

连接词	含义
AND	所有条件同时满足时触发
OR	任一条件满足时触发

模板或类型	trigger_condition 配置方式	补充说明
普通系统模板（如 table_row_count、null_rate、avg_value 等）	用户自定义。支持简单比较、区间、组合条件	无
data_timeliness 模板	无需填写，触发条件由系统固定	通过 filter 字段配置业务过滤逻辑
enum_range_consistency 模板	无需填写，触发条件由系统固定	通过 params.enum_values 配置合法枚举值列表
自定义 SQL	用户自定义。支持带字段名前缀的所有表达式格式	trigger_condition 中的字段名须与 SQL 返回的列名一致

字段	类型	必填	说明
rule_name	string	是	规则名称，建议使用描述性名称
rule_type	string	是	规则类型：system_template 或 custom_sql
trigger_condition	string	视模板而定	触发条件表达式（部分模板由系统固定，无需填写）
filter	string	否	可选，附加 WHERE 过滤条件

场景	推荐类型
标准的字段统计检查（空值率、重复值、均值等）	system_template
跨表数据一致性比对	custom_sql
复杂业务逻辑校验（格式、范围、关联检查等）	custom_sql
简单的表行数或及时性检查	system_template

质量规则配置指南

本页目录：

概述

核心概念

系统模板参考

触发条件表达式语法

简单比较

区间表达式

组合条件

自定义 SQL 字段名前缀

模板与触发条件兼容性约束

配置字段说明

通用字段

系统模板专用字段

自定义 SQL 专用字段

字段级规则专用字段

配置示例

表级规则示例

字段级规则示例

常见问题 FAQ