MQTT topics and wildcards: + and # explained with examples
An MQTT topic is a UTF-8 string with levels separated by slashes, such as plant/line-3/temp, that the broker uses to route messages. Subscribers can use two wildcards in topic filters: + matches exactly one level and # matches any number of levels and must come last. Publishers always publish to a full topic name without wildcards.
What an MQTT topic is
An MQTT topic is the address a message is published to. It is a UTF-8 string that the broker compares against subscriptions to decide who receives a message. Topics do not need to be created in advance. A topic exists as soon as a client publishes to it or subscribes to it.
The forward slash / separates a topic into levels:
plant/line-3/temp
fleet/ev-0042/soc
robot/arm-7/joint-3
enterprise/site-frankfurt/line-3/press-07/temp
The standard uses two terms. A topic name is the full topic in a PUBLISH. A topic filter is what a client puts in a SUBSCRIBE, and it may contain wildcards.
Rules for topic names
The MQTT 3.1.1 and 5.0 standards define these rules:
| Rule | Example |
|---|---|
| Topics are case-sensitive | plant/Line-3 and plant/line-3 are different topics |
| A topic must be at least one character long | An empty string is not a valid topic |
| Spaces are allowed but best avoided | plant/line 3 is valid |
| Empty levels are allowed | plant//temp has an empty second level |
| A leading slash creates an empty first level | /plant/line-3 is not the same as plant/line-3 |
| The null character (U+0000) is not allowed | |
| Maximum length is 65,535 bytes | Practical limits are usually set by the broker |
Wildcards + and # are not allowed in topic names |
They are only valid in topic filters |
The broker does not interpret the meaning of the levels. plant/line-3/temp is not a folder path. The structure only matters for wildcard matching and access control.
The single-level wildcard +
The plus sign + matches exactly one topic level. It must take up a whole level on its own.
mosquitto_sub -h broker.example.com -t 'plant/+/temp' -v
Filter plant/+/temp |
Matches? |
|---|---|
plant/line-3/temp |
Yes |
plant/line-4/temp |
Yes |
plant/line-3/press-07/temp |
No, two levels between plant and temp |
plant/temp |
No, the level for + is missing |
plant//temp |
Yes, + also matches an empty level |
You can use several + in one filter, for example fleet/+/+ to receive every second-level value for every vehicle. A filter such as plant/line+/temp is invalid, because + shares the level with other characters.
The multi-level wildcard
The hash sign # matches any number of levels, including zero. It must be the last character of the filter and take up a whole level.
mosquitto_sub -h broker.example.com -t 'robot/arm-7/#' -v
Filter robot/arm-7/# |
Matches? |
|---|---|
robot/arm-7/joint-3 |
Yes |
robot/arm-7/joint-3/torque |
Yes |
robot/arm-7 |
Yes, # also matches the parent level |
robot/arm-8/joint-3 |
No |
Invalid filters include robot/#/torque (not last) and robot/arm-7# (not on its own level).
A subscription to # alone receives every message on the broker, apart from $ topics. That is useful for debugging on a test system. On a production broker it can mean a very large message rate, and it should usually be blocked by access control.
$SYS and other topics starting with $
Topics that start with $ are reserved for the broker. A filter that begins with a wildcard does not match them. Neither # nor +/broker/uptime matches $SYS/broker/uptime. To receive them you must name the first level explicitly:
mosquitto_sub -h broker.example.com -t '$SYS/#' -v
$SYS/ is a widely used convention for broker statistics, but its content is not standardized. Each broker publishes different topics there. Applications should not publish to topics that start with $.
MQTT 5.0 defines one more $ prefix: shared subscriptions. A filter such as $share/historians/plant/# spreads matching messages across all clients in the group historians, instead of sending a copy to each one. This lets several instances of a consumer split the load.
How to design an MQTT topic hierarchy
A good topic hierarchy goes from general to specific, so that wildcards select useful groups. A common pattern in industry follows the physical plant structure:
enterprise/site/area/line/cell/measurement
enterprise/site-frankfurt/line-3/press-07/temp
With this structure, enterprise/site-frankfurt/# returns all data from one site, and enterprise/+/+/+/temp returns the temperature of every machine across sites. This kind of structure is the basis of a Unified Namespace.
Practical rules that save trouble later:
- Use lowercase only and one word separator, for example
-. - Do not start topics with
/. It adds an empty level for no benefit. - Avoid spaces and special characters. They are valid, but they complicate scripts and ACLs.
- Put the identifier of the device before the measurement, for example
fleet/ev-0042/soc, so thatfleet/ev-0042/#returns everything about one vehicle. - Keep payload data out of the topic. Do not put values or timestamps in topic levels. Each unique topic costs broker memory and makes subscriptions harder.
- Plan access control with the hierarchy. ACLs are usually written as topic filters, so a clear structure makes clear permissions.
- Write the scheme down and check it before new devices go live.
Topics and retained messages
Wildcard subscriptions also match retained messages. A client that subscribes to plant/# receives the stored retained message of every matching topic at once, followed by live updates. On a large hierarchy this can be many messages in a short burst, so consumers should be ready for it.