Merge pull request #10179 from kjellwinblad/kjell/fix/rule_engine_app_readme

docs: refine README.md for the emqx_rule_engine app

apps/emqx_rule_engine/README.md

@@ -1,23 +1,46 @@
 
-# emqx-rule-engine
+# Emqx Rule Engine
 
-IoT Rule Engine
+The rule engine's goal is to provide a simple and flexible way to transform and
+reroute the messages coming to the EMQX broker. For example, one message
+containing measurements from multiple sensors of different types can be
+transformed into multiple messages.
+
+
+## Concepts
+
+A rule is quite simple. A rule describes which messages it affects by
+specifying a topic filter and a set of conditions that need to be met. If a
+message matches the topic filter and all the conditions are met, the rule is
+triggered. The rule can then transform the message and route it to a different
+topic, or send it to another service (defined by an EMQX bridge). The rule
+engine's message data transformation is designed to work well with structured data
+such as JSON, avro, and protobuf.
+
+
+A rule consists of the three parts **MATCH**, **TRANSFORM** and **ACTIONS** that are
+described below:
+
+* **MATCH** - The rule's trigger condition. The rule is triggered when a message 
+  arrives that matches the topic filter and all the specified conditions are met.
+* **TRANSFORM** - The rule's data transformation. The rule can select data from the 
+  incoming message and transform it into a new message.
+* **ACTIONS** - The rule's action(s). The rule can have one or more actions. The 
+  actions are executed when the rule is triggered. The actions can be to route
+  the message to a different topic, or send it to another service (defined by
+  an EMQX bridge). 
 
-## Concept
 
-```
-iot rule "Rule Name"
-  when
-     match TopicFilters and Conditions
-  select
-    para1 = val1
-    para2 = val2
-  then
-    take action(#{para2 => val1, #para2 => val2})
-```
 
 ## Architecture
 
+The following diagram shows how the rule engine is integrated with the EMQX
+message broker. Incoming messages are checked against the rules, and if a rule
+matches, it is triggered with the message as input. The rule can then transform
+or split the message and/or route it to a different topic, or send it to another
+service (defined by an EMQX bridge).
+
+
 ```
           |-----------------|
  Pub ---->| Message Routing |----> Sub
@@ -28,11 +51,33 @@ iot rule "Rule Name"
           |   Rule Engine   |
           |-----------------|
                |      |
-        Backends Services Bridges
+           Services Bridges (defined by EMQX bridges)
 ```
 
-## SQL for Rule query statement
+## Domain Specific Language for Rules
+
+The **MATCH** and **TRANSFORM** parts of the rule are specified using a domain
+specific language that looks similar to SQL. The following is an example of a
+rule engine statement. The `from "topic/a"` part specifies the topic filter
+(only messages to the topic `topic/a` will be considered). The `where t > 50`
+part specifies the condition that needs to be met for the rule to be triggered.
+The `select id, time, temperature as t` part specifies the data transformation
+(the selected fields will remain in the transformed message payload). The `as
+t` part specifies that the `temperature` field name is changed to `t` in the
+output message. The name `t` can also be used in the where part of the rule as
+an alias for `t`.
+
 
 ```
-select id, time, temperature as t from "topic/a" where t > 50;
+select id, time, temperature as t from "topic/a" where t > 50
 ```
+
+ This just scratches the surface of what is possible with the rule engine. The
+ full documentation is available at [EMQX Rule
+ Engine](https://www.emqx.io/docs/en/v5.0/data-integration/rules.html). For
+ example, there are many built-in functions that can be used in the rule engine
+ language to help in doing transformations and matching. One of the [built-in
+ functions allows you to run JQ
+ queries](https://www.emqx.io/docs/en/v5.0/data-integration/rule-sql-jq.html)
+ which allows you to do complex transformations of the message.
+