# SQL 匹配失败告警处理指南

SQL 匹配失败告警表示在过去 30 分钟内，部署中数据集成规则执行失败的次数已超过设定阈值。

该情况通常意味着 EMQX Cloud 在执行数据集成规则时，消息已经进入规则引擎，但在 SQL 匹配或处理过程中发生异常，导致规则未能正确执行。常见问题包括消息 payload 的格式或编码不符合预期，或规则中使用的函数、表达式与实际数据结构不匹配。

## 消息 payload 格式或编码与预期不符

### 问题描述

当规则 SQL 接收到的消息 payload 不是合法的 JSON，或 payload 数据被截断、损坏，或编码方式不是 UTF-8 时，SQL 在解析 payload 或访问字段时可能失败，从而触发 SQL 匹配失败告警。

在部署**日志** 中，如果出现 `invalid_json`、`decode_json_failed` 等报错信息，则通常符合此类情况。

### 常见原因

- JSON 格式不合法，例如使用单引号代替双引号、存在尾随逗号。  
- 时间戳字段未按 JSON 规范使用字符串形式。  
- 消息 payload 在传输过程中被截断或损坏。  
- 消息编码不是 UTF-8。  

### 处理方法

- 确保客户端发送的消息 payload 格式正确、完整，并使用 UTF-8 编码。  
- 使用 MQTT 客户端订阅规则所筛选的主题，获取原始 MQTT payload 数据，对比分析格式问题并进行修复。  

## 函数或表达式类型或结构不匹配

### 问题描述

当规则 SQL 中使用的函数或 jq 表达式与实际 payload 中字段的类型或结构不一致时，函数执行可能失败或抛出异常，从而导致规则执行失败。

在部署**日志** 中，如果出现 `function_clause`、`jq_exception` 或 `jq error` 等报错信息，则通常符合此类情况。

### 常见原因

- SQL 中对字段类型的假设与实际 payload 不一致。  
- jq 表达式路径与实际 JSON 结构不匹配。  
- 对空值或缺失字段直接执行函数或表达式。  

### 处理方法

- 核对 payload 的实际结构和字段类型，并相应调整规则 SQL 逻辑。  
- 确保字段类型与所使用的函数或表达式匹配。  
- 在 SQL 或 jq 表达式中增加安全检查，例如使用 `is_not_null()` 等函数，避免对空值直接操作。  

## 排查步骤

1. 登录 EMQX Cloud 控制台。

2. 打开部署**日志**，将“错误类型”过滤为**数据集成**。

   - 若日志中出现 `invalid_json`、`decode_json_failed` 等报错，则通常属于**消息 payload 格式或编码与预期不符**场景。示例日志如下：

     ```text
     clientid: XXXXX, reason: {error,{decode_json_failed,...}}
     ```

   - 若日志中出现 `function_clause`、`jq_exception` 或 `jq error` 等报错，则通常属于**函数或表达式类型或结构不匹配**场景。示例日志如下：

     ```text
     WHERE clause exception for rule: XXXXX failed: {error,function_clause,...}
     ```

3. 从日志信息中获取对应的 `rule_id` 以及具体的报错原因。

4. 打开**数据集成** -> **规则**列表，根据 `rule_id` 定位到对应的规则，点击**编辑**，对 SQL 逻辑或相关配置进行修改。

   ![rule_sql_failed_edit](./_assets/rule_sql_failed_edit.png)

## 监控与统计

1. 在 EMQX Cloud 控制台的**数据集成** 页面中，可以查看单个规则 SQL 的执行成功次数与失败次数统计，用于持续观察规则执行情况。

   ![rule_sql_failed_stats](./_assets/rule_sql_failed_stats.png)

2. 打开**告警** -> **告警列表**，可查看 SQL 匹配失败告警的触发记录及其触发次数，用于判断问题是否已得到缓解。

   ![rule_sql_failed_alerts](./_assets/rule_sql_failed_alerts.png)