# ルール

ルール（ルールエンジンとも呼ばれます）は、EMQXに組み込まれたSQLベースのデータ処理コンポーネントです。これは[コネクター](./connectors.md)と連携して、コード不要でのIoTデータ抽出、フィルタリング、変換、保存、処理を可能にし、アプリケーション統合やビジネスイノベーションの加速を支援します。

## ルールの仕組み

ルールは、**データソース**からデータを取得し、**データ変換**を行い、その結果に対して適用すべき**アクション**を指定します。

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

- **データソース**：ルールのデータソースはメッセージ、イベント、または外部データシステムが該当します。ルールのSQLの`FROM`句でデータソースを指定し、`WHERE`句でルールが処理するメッセージに対する追加の制約を設定します。

  サポートされるさまざまなデータソースの種類や、`WHERE`句で参照可能なフィールドの詳細については、[SQLデータソースとフィールド](../rule_engine/rule_engine_events.md)を参照してください。

- **データ変換**：データ変換は入力メッセージの変換処理を指します。SQLの`SELECT`部分で入力メッセージからデータを抽出・変換します。埋め込みSQLのサンプル文を用いて、出力メッセージにタイムスタンプを追加するなどの高度な変換を実装可能です。

  構文や組み込みSQL関数の詳細は、[ルールSQLリファレンス](./rule-sql-syntax.md)および[組み込みSQL関数](./rule-sql-builtin-functions.md)を参照してください。SQL関数については[ jq関数](./rule-sql-jq.md)も参考になります。

- **アクション**：アクションは「処理済みデータをどこに送るか」という課題を解決します。EMQXプラットフォームに対し、ルールによって生成されたデータの取り扱い方法を指示します。入力が指定されたルールに従って処理された後、1つ以上のアクションを定義してSQL実行結果を処理します。ルールエンジンは対応するアクションを順次実行します。現在、ルールは以下の2種類のアクションをサポートしています：

  - 組み込みアクション：現在は[メッセージ再パブリッシュ](./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リファレンス](./rule-sql-syntax.md)を参照してください。

## ルールの作成

デプロイメントにアクセスし、左側ナビゲーションメニューから**データ統合**をクリックしてデータ統合ページに入ります。データ統合の初期ページにアクセスすると、必要に応じてデータ統合の種類を選択し、対応するアイコンをクリックしてターゲットサービスに接続するコネクターを作成できます。コネクター作成の具体的な手順は[コネクターの作成](./connectors.md#create-a-connector)およびデータ統合セクションの各種説明を参照してください。

::: tip

**新しいコネクター**をクリックすると、データ統合の初期ページに戻れます。

:::

クラウドリソース接続用のコネクターを作成したら、**ルール一覧**の左上にある**新しいルール**をクリックして**新しいルール**ページに入ります。コネクター一覧のルール作成ボタンからも新規ルールを作成可能です。

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

[メッセージ再パブリッシュ](./republish.md)用のルールを作成する場合は、**データ転送**カテゴリの**再パブリッシュ**をクリックしてルール作成を開始します。

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

また、**デバッグ**カテゴリの**何もしない（デバッグ）**をクリックしてルール作成プロセスに入ることもできます。これはアクションを持たない空のルールで、ルールのデバッグに特化しています。詳細は[空アクション（デバッグ）](./empty_action_debug.md)を参照してください。

### データソースの定義

**新しいルール**ページでルール名を入力し、将来の管理のためにメモを追加します。

**SQLエディター**で、ビジネスニーズに合ったデータソースを追加するために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`トピックにパブリッシュされたメッセージのペイロードに含まれる`timestamp`、`clientid`、温度（`temp`）、湿度（`hum`）を読み取ります。

### SQLジェネレーター

EMQX 5.91以降のDedicated版では、SQLエディターがAIによる自然言語からのルールSQL生成をサポートしています。この機能により、自然言語で意図を記述すると、システムが自動的に適切なSQL文を生成します。

利用手順：

1. **新しいルール**ページの**SQLエディター**セクションに移動します。

2. **SQLジェネレーター**ボタンをクリックして、**AIでSQL生成**ダイアログを開きます。

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

   ダイアログ内で以下の項目を指定します：

   - **タスク説明**（必須）：SQLに何をさせたいかを自然言語で記述します。

     例：*"MQTTメッセージのメタデータから`clientid`を抽出し、ペイロードから`device_id`と`temperature`を抽出する。トピック`sensors/temperature`のメッセージで温度が30を超える場合のみ適用する。"*

   - **関連トピック**（任意）：`sensors/temperature`のようなトピックフィルターを指定します。

   - **入力例（JSON）**（任意だが推奨）：AIがデータ構造を理解しやすくするため、MQTTメッセージペイロードのサンプルを提供します。例：

     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
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ペイロードを扱う場合

より詳細なカスタマイズや構文オプションは、[ルールSQL構文](./rule-sql-syntax.md)のドキュメントを参照してください。

### SQL文のテスト

**テストを有効にする**トグルスイッチをクリックして新規テストSQLを作成します。適切なテストパラメータを入力し、**テスト**ボタンを押します。

出力結果に期待されるデータ処理結果が表示されます。

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

## アクションの追加

ルール作成後、ルールにアクションを追加できます。詳細は[アクション](./actions.md)を参照してください。

## ルールのテスト

::: tip 注意

この機能はEMQX Dedicated版でのみ利用可能です。

:::

ルールエンジンはルールテスト機能を提供しており、シミュレートデータや実際のクライアントデータを使ってルールをトリガーし、ルールSQLを実行し、ルールに追加されたすべてのアクションを実行して、各ステップの実行結果を取得できます。

ルールをテストすることで、期待通りに動作するか検証でき、問題の早期発見と解決が可能です。これにより開発効率が向上し、本番環境での失敗を防止できます。

### テスト手順

1. **Try It Out**スイッチをオンにし、テスト対象として**ルール**を選択します。テスト開始前にルールを保存しておく必要があります。
2. **テスト開始**ボタンをクリックしてテストを開始します。ブラウザは現在のルールがトリガーされるのを待ち、テスト結果を生成します。
3. ルールをトリガーしてテストします。以下の2つの方法が利用可能です：
   - **シミュレートデータを使用**：**シミュレートデータ入力**ボタンをクリックし、ポップアップでSQLに合致する**データソース**を選択します。ルールの`FROM`句で指定されたソースと一致している必要があります。EMQXはすべてのフィールド（**クライアントID**、**ユーザー名**、**トピック**、**QoS**、**ペイロード**など）にデフォルト値を提供します。必要に応じて編集し、**テスト送信**ボタンを押して1回ルールをトリガーします。
   - **実際のデバイスデータを使用**：ページを開いたままにし、実際のクライアントやMQTTクライアントツールでEMQXに接続し、該当イベントをトリガーしてテストを行います。
4. テスト結果の確認：ルールがトリガーされると、コンソールに実行結果が出力され、各ステップの詳細な実行結果が表示されます。

### テスト例

[MQTTX](https://mqttx.app/)を使って再パブリッシュアクションのルールをテストできます。1つのクライアントを作成し、そのクライアントで`a/1`トピックをサブスクライブし、`t/1`メッセージを送信します。ダイアログボックスに、このメッセージが`a/1`トピックに再パブリッシュされる様子が表示されます。

MQTTXクライアントツールとEMQXの接続構築方法の詳細は、[MQTTX - はじめに](https://mqttx.app/docs/get-started)を参照してください。

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

対応して、コンソールにはルール全体の実行結果が表示され、以下の内容が含まれます：

- 左側はルール実行記録です。ルールがトリガーされるたびに記録が生成され、クリックすると該当メッセージやイベントの詳細に切り替えられます。
- 右側は選択されたルールのアクション記録一覧です。クリックするとアクションの実行結果やログを展開して確認できます。

ルールSQLまたはいずれかのアクションの実行が失敗した場合、該当ルール記録全体が失敗としてマークされます。記録を選択して該当アクションのエラー情報を確認し、トラブルシューティングが可能です。

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

上記例から、ルールは4回トリガーされ、そのうち3回は完全に成功しています。4回目は**HTTPサーバー**アクションの実行失敗により失敗しており、エラー原因はサービス利用不可です。

## ルール統計の確認

検証のために`temp_hum/emqx`トピックにメッセージを送信します。

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

ルール一覧でルールIDをクリックすると、ルールの統計情報およびこのルール配下のすべてのアクションの統計を実行統計ページで確認できます。

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

## アクション統計の確認

アクション一覧でアクションIDをクリックすると、アクション統計ページに移動し、このアクションのメトリクスやレート指標を閲覧できます。

::: tip

現在、個別アクションのメトリクス閲覧はDedicated版v5のデプロイメントのみサポートされています。

:::

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

## ルールの編集

**ルール**一覧で編集アイコンを直接クリックしてルールを編集できます。またはルールIDをクリックし、**設定**タブを選択して編集可能です。設定ページではルールのSQLテンプレート編集やアクションの編集・追加が行えます。

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

## ルールの有効化・無効化

ルール一覧で**有効**列のトグルスイッチをクリックして、ルールの有効化・無効化を切り替えられます。

## ルールの削除

ルール一覧で削除ボタンをクリックし、ルールIDを入力してルールを削除できます。

## アクションの有効化・無効化

::: tip 注意

この機能はEMQX Dedicated版でのみ利用可能です。

:::

アクション一覧で**有効**トグルスイッチをクリックするだけで、アクションのオン・オフを切り替えられます。

## アクションの編集・削除

**アクション**エリアで、**アクション名**列の名前または**アクション**列の編集ボタンをクリックしてアクションを編集できます。削除ボタンをクリックするとアクションを削除できます。