一、概述
配置文件支持以下能力：
·支持 系统模板（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_valuetrigger_condition: "null_count == 0" # SQL返回列名为null_counttrigger_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 中选择。