tencent cloud

Topic and Wildcard Subscriptions
Download PDF
Last updated:2026-01-30 14:59:41
Topic and Wildcard Subscriptions
Last updated: 2026-01-30 14:59:41
Download PDF
In the IoT world built on MQTT, the Publish-Subscribe (Publish/Subscribe) pattern achieves complete decoupling between devices and applications, while the core component enabling this mechanism is called the Topic (Topic).
and wildcard (Wildcard).
As a UTF-8 encoded string, Topic resembles a URL path with a hierarchical structure (such as sensor/room1/temperature). It serves not only as an addressing channel for message delivery but also as a mapping of business logic at the communication layer. During message routing, publishers send data to specific Topics, while the (Broker) precisely routes messages according to subscribers' requirements.
To address the complex communication needs of massive devices, MQTT introduces the wildcard subscription mechanism. This extends "exact matching" to "pattern matching," allowing clients to capture multiple related data streams with a single subscription, significantly reducing network load and client logic complexity. Therefore, deeply understanding the hierarchical logic of Topics and mastering the usage of wildcards is the first step in building scalable, maintainable, and high-performance IoT systems.

Topic Name, Topic Filter, and Topic

In the MQTT protocol communication mechanism, there are three roles: publisher, broker, and subscriber. Messages are sent from publishers to the broker and then received by subscribers, with Topics serving as the agreed message channel between publishers and subscribers. To achieve precise message routing, we need to clearly define these three roles:

Topic Name (Topic Name)

Definition: A string used when messages are published.
Purpose: To identify the unique channel for specific messages.
Rule: Wildcards must not be included. It must be a deterministic, concrete path.
Example: sensor/room1/temperature. The publisher instructs the Broker: "Deliver this message to the room1 temperature location."

Topic Filter (Topic Filter)

Definition: A string used when messages are subscribed to.
Purpose: To inform the Broker which messages you wish to receive.
Rule: Wildcards can be used, or not used (that is, exact matching). It is essentially a "matching template".
Example:
sensor/+/temperature: The subscriber tells the Broker: "I want the temperature data for all rooms."
sensor/room1/temperature: The subscriber tells the Broker: "I only want the temperature data for room1."

Topic (Subject)

Definition: It is a logical channel formed after the matching of Topic Name and Topic Filter within the Broker.
Relationship: Broker is responsible for matching Topic Name (message source) with Topic Filter (subscription requirement). If the match is successful, the message will be delivered.
Note:
In MQTT-based Message Queue, topics do not need to be created in advance. When clients subscribe to or publish messages, topics are automatically created, and there is no need to delete them.
To better understand the differences mentioned above, let's examine a typical MQTT publish and subscribe flow diagram: APP 1 subscribed to the topic sensor/+/temperature and will receive messages published by Sensor 1 and Sensor 2; after APP 2 subscribed to the topic sensor/2/temperature, it will receive messages published by Sensor 2 to this topic.


MQTT Wildcards

MQTT wildcards are a special type of Topic that can only be used for subscriptions (exclusively in Topic Filter), not for publishing. Clients can subscribe to topics containing wildcards to receive messages from multiple matching topics, thereby flexibly subscribing to multiple Topics and reducing overhead. MQTT supports two types of wildcards: + single-level wildcard and # multi-level wildcard.

Single-Level Wildcard

The single-level wildcard is represented by a plus sign +, which can be used to match a single topic level. This wildcard must occupy an entire level and cannot be part of a level (for example, room+ is invalid). By subscribing to a topic with a single-level wildcard, it can match any topic where the wildcard position is replaced by an arbitrary string. For example:
Subscribe to sensor/+/temperature
Match sensor/bedroom/temperature
Match sensor/living_room/temperature
Does not match sensor/bedroom/upstairs/temperature (because + can only match one level).
sensor/temperature is not matched (because there is a missing level between sensor and temperature).

Multi-level Wildcard

The multi-level wildcard is represented by a number sign #, which matches zero or more arbitrary topic levels. It must be the last character of the topic filter and preceded by a forward slash. For example:
Subscribe to sensor/bedroom/#
Match sensor/bedroom/temperature
Match sensor/bedroom/humidity
Match sensor/bedroom/light/intensity
Match sensor/bedroom (# can match zero levels).
sensor/living_room/temperature is not matched (because bedroom is fixed).
Note: If the service is expected to have high throughput, using only multi-level wildcards for subscriptions may constitute a "bad" practice. Subscribing to overly broad topics can result in a large volume of messages being delivered to the client, potentially impacting system performance and bandwidth consumption. Follow best practices to optimize Topic Filter design and avoid unnecessary message overload.

Topics Starting with $

Event Topic $events

The MQTT system publishes triggered events to the following system topics as QoS=0 messages. Business systems can subscribe to them based on business needs.
Topic name
Remarks
$events/client_connected
Client connected.
$events/client_disconnected
Client disconnected.
$events/session_subscribed
A subscription was added to the client session.
$events/session_unsubscribed
A subscription was removed from the client session.
$events/certificate_registered
Client registered a device certificate.
$events/certificate_rejected
Client device certificate was rejected. The certificate status is inactive, such as PENDING_ACTIVATION.

Shared Subscription

Shared subscription is a new feature introduced in MQTT 5.0 that enables load balancing of subscriptions among multiple subscribers. The shared subscription topic specified by MQTT 5.0 begins with $share.
Shared subscription Topic Filter is configured as follows: $share/{ShareName}/{TopicFilter}
Parameter
Description
$share
Literal constant, a fixed string.
{ShareName}
It is the name of a shared subscription group and must not contain " / ", " + ", " # ".
{TopicFilter}
The requirements and semantics are the same as those of MQTT TopicFilter.

MQTT Topic Usage Recommendations

1. Case-sensitive: myhome/temp and MyHome/Temp are completely distinct topics.
2. Hierarchy and Character Limitation:
Hierarchy Depth: It is recommended to keep it within 7 levels. The deeper the hierarchy, the higher the resource consumption for matching by the Broker.
Character Type: Each topic must contain at least one character; avoid spaces and non-ASCII special characters.
Naming Convention: Within the same topic hierarchy level, it is recommended to use underscores "_" or hyphens "-" to connect words (or use camel case).
3. Place Unique Identifiers First: When wildcards are used, position the topic level with unique values (such as device ID) as close to the first level as possible. For example: device/{deviceID}/status is preferable to device/status/{deviceID}.
4. Documentation: Maintain comprehensive documentation detailing your MQTT topic structure, including its purpose, expected message payload, and other complete conventions or guidelines.

FAQs

Topic Hierarchy and Length Limitations

The MQTT protocol specifies that the topic length is limited to two bytes, allowing a maximum of 65,535 characters per topic.
It is recommended to keep the topic hierarchy within 7 levels. Using shorter topic names and fewer hierarchy levels means less resource consumption. For example, my-home/room1/data is better than my/home/room1/data.

Does the Server Have a Limit on the Number of Topics?

Different message servers vary significantly in their support for the maximum number of topics. Currently, there is no default limitation on the number of topics. However, a larger number of topics will consume more server memory and incur higher routing lookup overhead. Given that the number of devices connected to the MQTT Broker is generally substantial, we recommend limiting the number of topics subscribed by a single client to 10 or fewer.

Whether the Performance of Wildcard Topic Subscriptions Is Consistent With That of Regular Topic Subscriptions

Wildcard topic subscriptions have lower performance and consume more server resources than regular topic subscriptions; users can choose the subscription type based on actual business needs.

How to Use System Topics?

Subscribe to specific event topics based on business needs. For details, refer to Event Topics $events. Subscribing to $events/# will receive messages for all client events.

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback