Skip to content
IndraMQTT

Rules

Rules

A rule reads each message once at ingress. It filters rows with WHERE. It shapes rows with SELECT. It sends each result to a topic or to a connector.

Use rules when a message must fan out, change shape, or leave the broker. You get SQL over live MQTT traffic with no second process. The complete MQTT platform in one small binary: broker, SQL rules, data connectors and multi-tenancy in a single process.

flowchart LR
    Pub["publisher :1883"] -- "PUBLISH" --> Engine["rule engine"]
    Engine -- "WHERE filter" --> Match["matched rows"]
    Match -- "SELECT shape" --> Out["republish topic"]
    Match -- "INTO connector id" --> Conn["connectors"]
    Conn -- "batch send" --> Ext["external system"]

Before you start

  • Install the broker from Install.
  • Keep ports 1883 and 18083 free.
  • Read Concepts for topics and wildcards.

In this section

PageWhat it covers
Rule SQLSELECT, FROM, WHERE, FOREACH, CASE, operators, event sources, windows.
Clauses and operatorsOne verified entry per SQL clause and operator.
FunctionsEvery built-in function by group, with call shape and arity.
Message context functionsOne verified entry per message context accessor.
Math and bitwise functionsOne verified entry per math and bitwise function.
Bit and byte functionsOne verified entry per bit and byte function.
Type conversion functionsOne verified entry per type conversion function.
Type check functionsOne verified entry per type check function.
Array functionsOne verified entry per array function.
Hashing functionsOne verified entry per hashing function.
Compression functionsOne verified entry per compression function.
Rule state functionsOne verified entry per rule state function.
ActionsBuilt-in actions, a tested republish example, how to test a rule, limits.
Rule actions AOne verified entry per action from alloydb to dynamodb.
Rule actions BOne verified entry per action from elasticsearch to opentsdb.
Rule actions COne verified entry per action from oracle to webhook.
Rule eventsOne verified entry per rule event source.

[!NOTE] A rule keeps the tenant of its input message. A rule of tenant A never fires for a publish of tenant B. See Multi-tenancy.

Check that it works

Start the broker with this file. The health endpoint returns OK.

[node]
id = "docs-rules"


[listeners.tcp]
bind = "0.0.0.0:1883"


[listeners.api]
bind = "0.0.0.0:18083"


[logging]
level = "warn"


[auth]
allow_anonymous = true


[rules_engine]
window_channel_depth = 65536
Terminal window
python3 - <<'PY'
import os, socket
port = int(os.environ.get("API_PORT", "18083"))
sock = socket.create_connection(("127.0.0.1", port), timeout=5)
sock.sendall(b"GET /healthz HTTP/1.0\r\nHost: docs\r\n\r\n")
print(sock.makefile().read().strip().splitlines()[-1])
PY
OK

API errors

Creating a rule with an id that already exists returns 400 BAD_REQUEST. The existing rule and its stored settings do not change. A rule whose FROM clause is absent or invalid returns 400 BAD_REQUEST with a message that names the problem. The broker never substitutes a topic. PUT /api/v5/rules/{id} merges the fields that the body carries. An omitted field keeps its stored value. Testing an absent rule with POST /api/v5/rules/{id}/test returns 404 RULE_NOT_FOUND. The test creates no rule.

Next steps