# SQLマッチング失敗アラート

SQLマッチング失敗アラートは、過去30分間におけるデプロイメント内のデータ統合ルール実行失敗回数が設定された閾値を超えたことを示します。

これは通常、メッセージがルールエンジンに入ったものの、SQLマッチングや処理中にエラーが発生したことを意味します。一般的な原因としては、予期しないペイロードの形式やエンコーディング、実際のデータ構造と合わない関数や式の使用などが挙げられます。

## 予期しないペイロード形式またはエンコーディング

### 症状

メッセージペイロードが有効なJSONでない、途中で切れている、破損している、またはUTF-8エンコーディングが使用されていないため、ルールSQLがフィールドの解析やアクセスに失敗します。

**デプロイメントログ**における `invalid_json` や `decode_json_failed` といったエラーは通常、この状態を示します。

### 主な原因

- ダブルクォーテーションではなくシングルクォーテーションを使う、末尾のカンマがあるなどの無効なJSON構文。
- タイムスタンプ値が必要な場合にJSON文字列として表現されていない。
- ペイロードが転送中に切断または破損している。
- UTF-8エンコーディングが使用されていないペイロード。

### 解決策

- クライアントが完全で有効なUTF-8エンコード済みペイロードを送信していることを確認してください。
- ルールで選択されたトピックにMQTTクライアントをサブスクライブし、元のペイロードをキャプチャして期待される形式と比較してください。

## 関数または式の型や構造の不一致

### 症状

ルールSQL内の関数やjq式が、実際のペイロードのフィールドの型や構造と合わず、ルール実行が失敗します。

**デプロイメントログ**における `function_clause`、`jq_exception`、`jq error` といったエラーは通常、この状態を示します。

### 主な原因

- ルールSQLが実際のペイロードと異なるフィールド型を想定している。
- jq式のパスが実際のJSON構造と一致していない。
- 関数や式がnullまたは存在しないフィールドに対して直接操作を行っている。

### 解決策

- 実際のペイロードの構造とフィールド型をルールSQLと比較し、SQLを適切に更新してください。
- 各フィールドの型が、それを使用する関数や式と互換性があることを確認してください。
- オプションのフィールドに対して操作を行う前に、`is_not_null()` のようなガードをSQLやjq式に追加してください。

## トラブルシューティング

1. EMQX Cloudコンソールにログインします。

2. **デプロイメントログ**を開き、**エラータイプ**を**データ統合**に設定します。

   - `invalid_json` や `decode_json_failed` といったエラーは通常、**予期しないペイロード形式またはエンコーディング**を示します。例：

     ```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や関連設定を更新します。

   ![ルールSQL編集](./_assets/rule_sql_failed_edit.png)

## 監視と統計

1. **データ統合**ページで、個別ルールの成功・失敗回数を確認し、SQL実行状況を監視します。

   ![ルールSQL実行統計](./_assets/rule_sql_failed_stats.png)

2. **アラート** -> **アラート一覧**に移動し、SQLマッチング失敗アラートの記録や発生頻度を確認します。

   ![SQLマッチング失敗アラート記録](./_assets/rule_sql_failed_alerts.png)