# 规则

规则引擎是 EMQX 内置的数据处理功能，它使用 SQL 语句编排规则，并通过消息、客户端事件以及外部数据系统触发，无需编写代码即可实现一站式的 IoT 数据提取、过滤、丰富和转换处理，并将处理完成后的数据输出到动作或外部数据系统中。

规则是构成 EMQX 强大的数据集成能力的一部分，配合使用 Sink/Source 提供了清晰、灵活的业务集成方案，能够简化业务开发流程，提升用户易用性并降低业务系统与 EMQX 的耦合度。详情请查看[规则引擎](../data-integration/rules.md)。

在左侧的**集成**菜单下，用户可以进入到规则页面。规则页面中用户可以创建和管理创建好的规则。

## 创建规则

创建规则可以在规则页面的右上角，点击**创建**即可进入到创建规则页面。也可以在连接器页面，使用已经创建好的连接器，来快速创建一个规则。

### SQL 编辑器

进入到创建规则页面可以看到一个 SQL 编辑器，规则是基于 SQL 语句来使用的，您可以使用 SQL 语句来实时的查询过滤，转换和丰富客户端之间或系统业务之间的数据。顶部两个输入框分别为**规则 ID** 和**备注**，进入创建页面后，会随机生成一个规则 ID 来标识当前规则，也可以手动输入你想要输入的规则标识，可以在备注中输入一些规则的描述信息来区分每个规则的使用。

点击 SQL 编辑器下方的 **SQL 示例**会在右侧弹出不同的 SQL 模版供您选择以快速创建规则。目前提供了以下比较常用的 SQL 模版：

- 选择指定主题的消息
- 同时处理客户端连接、断开连接事件
- FOREACH 处理 JSON 数组并逐个输出
- FOREACH 处理 JSON 数组选择指定字段并添加过滤条件
- CASE-WHEN 从多个条件列表返回可能结果
- 数组处理 - 从 JSON 格式的 payload 中获取嵌套的值

SQL 语句默认为 `SELECT * FROM "t/#"`，其含义为当客户端向 `t/#` 这个主题发送消息时，我们就取出当前事件下所有的数据信息。`SELECT` 关键词可以获取消息中的所有字段，例如可以获取当前消息的 `Payload`，则 SQL 语句可以修改为 `SELECT payload from "t/#"`，获取的内容可以使用[内置函数](../data-integration/rule-sql-builtin-functions.md)来进行处理和转化，`FROM` 关键词后面输入数据源，即事件主题，下方规则调试部分可查看到所有可选的数据源事件，使用 `WHERE` 关键词，可以添加条件判断，更多详细的 SQL 语法使用，请参考 [SQL 语法与示列](../data-integration/rule-sql-syntax.md)。

### 启用调试

当完成 SQL 语句的编写后，可以在页面底部的调试区域打开**启用调试**按钮对 SQL 进行测试。选择触发规则的事件或消息来源，输入模拟的测试数据后，点击 SQL 编辑器下方的**运行测试**按钮，即可在页面底部的输出结果中看到规则的执行结果。

在每次更改完成 SQL 语句后都可以通过启用调试来测试规则的执行结果，以确保规则的正确性。

::: tip

执行 SQL 时如果出现 `412` 的错误码提示时，可能是与测试数据不匹配造成的，且当数据来源与 SQL 语句不匹配时也会提示选择与其对应的事件或消息来源。更新数据来源事件后，测试数据会自动更新为对应的数据格式

:::

调试时的数据来源与真实使用场景下的一致，包含有一些 MQTT 事件，对于消息部分，我们可以选择不同的消息来源来模拟数据，包括：

- 消息发布（mqtt topic）
- 消息投递（$events/message/delivered）
- 消息确认（$events/message/acked）
- 消息丢弃（$events/message/dropped）

对于其它事件，我们可以选择不同的客户端和会话事件来模拟数据，包括：

- 连接完成（$events/client/connected）
- 连接断开（$events/client/disconnected）
- 连接确认（$events/client/connack）
- 鉴权完成（$events/auth/check_authz_complete）
- 认证完成（$events/auth/check_authn_complete）
- 订阅（$events/session/subscribed）
- 取消订阅（$events/session/unsubscribed）

对应的数据源需要与编辑器中的 SQL 语句保持一致，当需要使用上述中的一些消息事件或 Source 来获取数据时，需要将对应的事件主题（括号中的内容）填写到 SQL 语句中， `FROM` 关键词的后面，规则支持使用多个事件。更多详细的数据源与事件解释，请参考 [SQL 数据源和字段](../data-integration/rule-sql-events-and-fields.md)。

您还可以在调试区域对规则进行测试，详细的测试步骤，参考[测试规则](../data-integration/rule-get-started.md#测试规则)。

![image](./assets/rule-test.png)

### 动作输出

完成 SQL 语句的编辑和规则调试后，您可以得到一个符合我们需求的输出结果，这时可以在页面右侧的**动作输出**标签中选择规则触发执行后，需要继续执行的动作。点击**添加动作**按钮，您可以选择动作来继续处理规则的输出结果。

其中包括以下内置动作：

- 控制台输出，可以打印结果输出到控制台，可以用于真实场景下的调试。
- 消息重发布，可以将规则处理后的输出结果，再次发布到指定的主题中。

如果使用外部动作转发数据，可以创建一个新的动作，也可以选择已经创建好的动作。选择动作后，规则的输出结果将转发到对应的外部数据系统上，有关每个动作的配置可参考动作页签。

更多关于规则动作的详情，请参考[添加动作](../data-integration/rule-get-started.md#添加动作)。

## 规则列表

当创建完成一个规则后，可以在规则列表中查看到该规则的基本信息，包含规则 ID、规则接入数据的输入（例如事件，主题和 Source 等）、规则的备注、启动状态、规则创建时间, 规则列表中的规则可以进行设置、删除、启用、禁用等操作。点击规则 ID 可以查看规则的详细信息。还可以在更多操作里，选择快速复制一个规则并修改，最大程度提升规则的复用性。

列表顶部包含有一个搜索栏，我们可以使用规则的 ID，接入数据的主题，是否启用和备注来进行多条件的规则查询，帮助用户快速找到符合条件的规则并进行查看和设置等。注意：规则 ID 和备注支持模糊查询，主题支持切换为使用通配符来搜索。

![image](./assets/rule-list.png)

## 规则概览

在规则列表页面，点击规则 ID，可以快速进入规则的概览页面，规则概览页面包含了规则的基本数据统计包括：规则的运行时的统计，当前规则下动作的执行统计。例如规则的命中数，命中并通过的数量，规则的执行速率，失败数，执行动作成功和失败数等。点击右上角的**刷新**图标可以实时的查看当前规则的运行数据统计。

![image](./assets/rule-overview.png)

## 规则设置

点击**设置**标签，可以进入到规则的设置页面，规则设置页面包含了规则的基本信息，设置页面可以进行规则的修改和调试，与创建页面相同。例如需要修改当前规则下的执行动作，修改规则的备注，重新编辑 SQL 语句等。

![image](./assets/rule-settings.png)