MQTT GUIDE
3 min readMQTT Topics and Wildcards
MQTT topics are hierarchical, slash-separated strings (e.g. sensors/floor1/temp) that messages are published to and clients subscribe to. Subscriptions can use wildcards: + matches a single level and # matches all remaining levels.
MQTT has no addresses or routing tables — messages are addressed by topic. A publisher tags each message with a topic string, and the broker delivers it to whoever subscribed to a matching topic. Getting your topic structure right is most of the work of designing an MQTT system.
Topic hierarchy
A topic is a UTF-8 string divided into levels by a forward slash, such as
sensors/floor1/temp. The hierarchy is yours to design; the broker treats each level as opaque text.
Topics are case-sensitive, may be up to 65,535 bytes long, and are created implicitly — you never pre-register a
topic, you just publish to it.
Wildcards
Publishers always use a full, specific topic. Subscribers can widen their interest with two wildcards:
-
+— single-level wildcard. It matches exactly one level, sosensors/+/tempmatches every floor's temperature. -
#— multi-level wildcard. It matches the current level and everything below it, sosensors/#matches all topics undersensors. It must be the last character of the filter.
Naming best practices
If two of a client's subscriptions both match a message (say sensors/# and sensors/+/temp), the broker usually delivers a single copy at the highest matching QoS rather than one per subscription — as TBMQ
does, though the MQTT spec technically permits either.
Topics in TBMQ
TBMQ matches subscriptions with an in-memory topic trie, so a published message is
routed by walking its topic levels and match cost scales with a topic's depth rather than its total subscription
count. You can cap how deep topics may go with MQTT_TOPIC_MAX_SEGMENTS_COUNT to keep matching predictable,
and the
$share/ prefix turns a normal subscription into a load-balanced
shared subscription. See the
topics reference for the full matching rules.
Frequently asked questions
What is an MQTT topic?
A topic is a UTF-8 string that names the subject of a message, split into levels by forward slashes — for example sensors/floor1/temp. Publishers send to a full topic and subscribers register interest in topics, and the broker routes each message to the matching subscribers.
What is the difference between + and # wildcards?
The + wildcard matches exactly one topic level, so sensors/+/temp matches sensors/floor1/temp and sensors/floor2/temp. The # wildcard matches the current level and everything beneath it, so sensors/# matches all topics under sensors. # must be the last character of the filter; + can appear at any level.
Can you publish to a wildcard topic?
No. Wildcards are only valid in subscriptions. A published message must go to a specific, fully qualified topic — the broker needs one concrete destination to route from.
Are MQTT topics case-sensitive?
Yes. sensors/Temp and sensors/temp are different topics. Topics are also created on the fly — there is no need to register or pre-declare a topic before publishing to it.
What makes a good MQTT topic structure?
Use a consistent, hierarchical scheme that goes from general to specific, such as site/area/device/metric. Avoid leading slashes and spaces, keep names predictable, and design the hierarchy so common subscriptions map cleanly to a single-level (+) or multi-level (#) wildcard.
Run it yourself
TBMQ is a free, open-source MQTT broker built to scale. Spin it up in minutes or try the live demo — no install required.