learn/mqtt

MQTT topics and wildcards: + and # explained with examples

Short answer

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.

Updated:

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 that fleet/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.

01ultramq/learn/faq

Frequently asked questions

What is the difference between + and # in MQTT?

The + wildcard matches exactly one topic level, while # matches any number of levels, including zero, and must be the last character of the filter. For example, plant/+/temp matches plant/line-3/temp, and plant/# matches every topic under plant.

Can I publish to an MQTT topic with a wildcard?

No. Wildcards are only allowed in subscriptions. A PUBLISH must use a full topic name, and the broker treats a topic name containing + or # as a protocol error and closes the connection.

Are MQTT topics case-sensitive?

Yes. Plant/Line-3 and plant/line-3 are two different topics. Most teams use lowercase only to avoid mistakes.

Should an MQTT topic start with a slash?

It is best not to. A leading slash creates an empty first level, so /plant/line-3 and plant/line-3 are different topics, which leads to confusing subscriptions.

03ultramq/start

Talk to an engineer about your project.

Tell us what you want to connect, where it has to run and what the data should feed. We reply by email.

SUBultramq/#