# 规则

规则是 EMQX Cloud 内置基于 SQL 的数据处理组件，搭配[连接器](./connectors.md)使用无需编写代码即可实现一站式的 IoT 数据提取、过滤、转换、存储与处理，以加速应用集成和业务创新。

## 规则的组成
规则描述了 **数据来源**、**数据处理过程**、**处理结果去向** 三个方面：

![rules](./_assets/rule_01.png)

- **数据来源**：规则的数据源可以是消息或事件，也可以是外部的数据系统。规则通过 SQL 的 FROM 子句指定数据的来源，SQL 的 WHERE 子句用于过滤数据。有关支持的各种类型数据源和可以在 WHERE 子句中引用的字段的更多信息，请参阅 [SQL 数据源和字段](../rule_engine/rule_engine_events.md)。

- **数据处理过程**：规则通过 SQL 语句和函数来描述数据的处理过程。SQL 的 SELECT 子句以及 SQL 函数用于提取和转换数据；嵌入的 SQL 示例语句可用于实现高级转换，例如向输出消息添加时间戳。

  有关语法和内置 SQL 函数的详细解释，请参阅[规则 SQL 语法与示列](./rule-sql-syntax.md)和[内置 SQL 函数](./rule-sql-builtin-functions.md)。要了解更多关于 SQL 函数的信息，您还可以参考 [jq 函数](./rule-sql-jq.md)。

- **处理结果去向**：动作解决了“将处理后的数据发送到哪里”的问题。它们告诉 EMQX Cloud 如何处理规则产生的数据。在根据指定的规则处理输入之后，可以定义一个或多个动作来处理 SQL 执行结果。规则引擎将依次执行相应的动作。目前，规则支持以下两种类型的动作：

  - 内置动作：目前，您可以通过[消息重新发布](./republish.md)将处理结果发布到另一个 MQTT 主题。 
  - 将处理结果存储在数据库中：通过预定义的[连接器](./connectors.md)将数据发送到各类目标服务。

### 规则 SQL 语句简介
SQL 语句用于指定规则的数据来源、定义数据处理过程等。下面给出了一个 SQL 语句的例子：

```sql
SELECT
    payload.data as d
FROM
    "t/#"
WHERE
    clientid = "foo"
```

在上述 SQL 语句里：

- 数据来源：主题为 t/# 的消息；
- 数据处理过程：如果发送消息的客户端 ID 为 foo，则从消息内容中选出 data 字段并赋值给新的变量 d。

::: tip
"." 语法要求数据必须是 JSON 或者 Map 类型，如果是其他数据类型，须要使用 SQL 函数做数据类型转换。
:::

关于规则的 SQL 语句格式和用法，详见 [SQL 手册](https://docs.emqx.com/zh/enterprise/latest/data-integration/rule-sql-syntax.html)。

## 创建规则

进入到您的部署，并从左侧导航菜单点击**数据集成**进入数据集成页面。当您首次进入数据集成的初始页面，您可以根据需要选择数据集成的类型，通过点击相应的图标创建一个用于连接到目标服务的连接器。具体的连接器创建步骤，参阅[创建连接器](./connectors.md)和各数据集成页面。

::: tip

您可以通过点击**新建连接器**回到数据集成初始页面。

:::

当您已经完成了连接器的创建，点击**规则列表**左上角的**新建规则**按钮，进入新建规则页面。您也可以通过点击连接器列表中的规则创建图标来创建新的规则。

![rules](./_assets/rule_02.png)

对于**消息重新发布**类型，您无需创建连接器，可以在数据集成初始页面直接点击图标开始规则的创建过程。

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

您还可以在**调试**分类下点击**空动作**进入规则创建过程。空动作只配置规则，不关联任何动作，可以用来专门做规则的调试。具体内容参阅[空动作（调试）](./empty_action_debug.md)。

### 定义数据源

在**新建规则**页面上，为您的规则输入名称并添加备注以便未来管理。

在 **SQL 编辑器**中，您可以自定义语句以添加适合您业务需求的数据源。可以输入以下 SQL 语句用于演示：

```sql
SELECT
  timestamp as up_timestamp, clientid as client_id, payload.temp as temp, payload.hum as hum
FROM
  "temp_hum/emqx"
```

通过指定此 SQL 语句，规则从发布到 `temp_hum/emqx` 主题的消息中读取报告的时间戳、clientid 以及包含在消息 payload 中的温度和湿度。

### SQL 生成器

从 EMQX 5.91 以及之后的专有版部署开始，SQL 编辑器支持通过 AI 驱动的 SQL 生成器，使用自然语言生成规则 SQL。该功能允许您用自然语言描述预期行为，系统将自动生成相应的 SQL 语句用于规则引擎。

SQL 生成器默认处于启用状态。您可以通过 Dashboard 右上角的**设置**菜单中的开关将其禁用。

要使用该功能，请按照以下步骤操作：

1. 进入**创建规则**页面，找到 **SQL 编辑器**区域。

2. 点击 **SQL 生成器**按钮，打开**使用 AI 生成 SQL** 对话框。

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

   根据以下提示填写字段：

   - **任务描述**（必填）：使用自然语言描述您希望 SQL 实现的逻辑。

     示例： *“从 MQTT 消息的元数据中提取 `clientid`，并从 payload 中提取 `device_id` 和 `temperature`。仅匹配来自主题 `sensors/temperature` 且温度大于 30 的消息。”*

   - **相关主题**（可选）：指定要匹配的主题过滤器，如 `sensors/temperature`。

   - **输入示例（JSON）**（可选但推荐）：提供一条 MQTT 消息的 payload 示例，帮助 AI 更好地理解数据结构。 示例：

     ```json
     {
       "device_id": "sensor001",
       "temperature": 32.5,
       "unit": "C"
     }
     ```

   - **输出示例（JSON）**（可选）：指定期望的输出格式。 示例：

     ```json
     {
       "clientid": "client_a1b2c3",
       "device_id": "sensor001",
       "temperature": 32.5
     }
     ```

     ::: tip

     提供输入和输出示例可以显著提升 SQL 生成的准确性。

     :::

3. 点击**生成**以预览生成的 SQL。

4. 在预览对话框中，您可以：

   - 查看并手动编辑生成的 SQL；
   - 点击**应用 SQL**，将其插入到 SQL 编辑器中；
   - 或点击**返回表单**，修改任务描述或示例后重新生成。

5. 如果点击**应用 SQL**，生成的 SQL 将自动出现在 **SQL 编辑器**中，您可继续查看和修改。

#### 示例结果

根据上面的任务描述和示例，生成的 SQL 可能如下所示：

```sql
SELECT
  clientid,
  payload.device_id AS device_id,
  payload.temperature AS temperature
FROM
  "sensors/temperature"
WHERE
  payload.temperature > 30
```

该规则从主题 `sensors/temperature` 中提取 `clientid`、`device_id` 和 `temperature` 字段，并只处理温度大于 30 的消息。

#### 使用 SQL 生成器的场景

SQL 生成器特别适用于以下情况：

- 您不熟悉 EMQX SQL 语法；
- 您希望快速原型设计一个规则；
- 您正在处理结构化的 JSON 消息 payload。

如需更多自定义功能和语法说明，请参阅 [SQL 语法与示例](./rule-sql-syntax.md)文档。

### 测试 SQL 语句

点击**启用调试**开关来创建新的测试 SQL。填写适当的测试参数，并点击**测试**按钮。

在输出结果中，您可以看到预期的数据处理结果。

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

## 动作

创建规则之后，您可以为规则添加动作。详细内容，参考[动作](./actions.md)。

## 测试规则

::: tip 注意

测试规则功能仅适用于专有版部署。

:::

规则引擎提供了规则测试功能，可以使用模拟数据或真实客户端触发规则，执行规则 SQL 以及规则中添加的所有动作，并获得每个步骤的执行结果。

通过测试规则，可以验证规则是否按预期工作，快速排查并解决存在的问题。这不仅加快了开发速度，还确保了规则在实际运行时能够如期运行，避免在真实环境中出现故障。

### 测试步骤

1. 点击**启用调试**开关，并将测试目标选择为**规则**。注意，开始测试之前需要先保存规则。

2. 点击**开始测试**按钮开始测试，浏览器将等待当前规则触发以生成测试结果。

3. 触发规则进行测试，支持以下 2 种方式：

   - **模拟数据**：点击**输入模拟数据**按钮，在弹出的窗口中选择与 SQL 匹配的**数据来源**，并确保它与规则中指定的来源（FROM 子句）保持一致。

     EMQX 为所有字段提供了默认值，例如**客户端 ID**、**用户名**、**主题**、**QoS**、**Payload** 等。可以修改为需要的值，点击**提交测试**按钮即可触发一次规则进行测试。

   - **真实设备**：保持当前页面打开，使用真实客户端或 MQTT 客户端工具连接到 EMQX，触发对应的事件，进行测试。

4. 查看测试结果：当规则被触发时，会将执行结果输出到控制台上，详细展示每个步骤的执行结果。

### 测试示例

以测试一个使用了默认规则 SQL 并添加了消息重发布动作的规则为例，您可以使用 [MQTTX](https://mqttx.app/zh/docs/get-started) 创建一个客户端，然后使用此客户端订阅主题 `a/1` 并发送一条 `t/1` 的消息。您将在对话框中看到此消息被重新发布到主题 `a/1`：

![mqttx-test-rule](./_assets/mqttx-test-rule.png)

相应的，控制台测试界面上将显示整个规则的执行结果，显示内容如下：

- 左侧为规则执行记录，每次规则触发会产生一条记录，点击可以切换到对应的消息或事件详情。
- 右侧为选中规则记录下的动作列表，点击可以展开查看动作执行结果和日志。

当规则 SQL 或任意动作执行失败时，整个规则记录将标记为失败状态，可以选中记录查看对应动作的错误信息进行排查。

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

从上图可以看到，规则被触发了 4 次，其中 3 次规则执行完全成功，第 4 次由于 **HTTP 服务**动作执行失败，错误原因是服务不可用。

## 查看规则统计

您可以使用 [MQTTX](https://mqttx.app/) 连接到部署并模拟温湿度数据上报，发送消息到 `temp_hum/emqx` 主题以进行验证。

```json
{
  "temp": "27.5",
  "hum": "41.8"
}
```

点击**规则列表**中的规则 ID，在运行统计页面可以查看到规则的统计以及此规则下所有动作的统计。点击页面右上角的重置按钮可以重置指标数据。

::: tip

Serverless 部署不支持重置指标。

:::

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

## 查看单个动作统计

点击**输出动作列表**中的动作 ID，在运行统计面板中可以查看到此动作的指标统计和速率统计。点击右上角的重置按钮可以重置指标数据。

::: tip

目前只有专有版 v5 部署支持查看单个动作的指标。

:::

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

## 编辑规则

您可以直接点击规则列表上的编辑图标来编辑该规则，也可以通过点击规则 ID，然后选择**设置**页签来编辑该规则。在设置页面，你可以编辑规则的 SQL 模板，同时可以编辑、添加动作。

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

## 启用和停用规则

可以在规则列表上启用和停用规则。点击**是否启用**开关即可开启或停用规则。

## 删除规则
可以在规则列表删除规则。点击删除按钮，输入规则 ID 后可删除规则。

## 启用或停用动作

::: tip 注意

该功能仅适用于专有版部署。

:::

可以在动作列表上启用和停用动作。点击**是否启用**开关即可开启或停用动作。

## 编辑和删除动作

可以在动作列表点击**动作名称**或编辑按钮，重新编辑动作。点击**删除**按钮删除动作。