Syntax
- Shared filter form:
$share/{ShareName}/{TopicFilter}. - ShareName must not contain
/,+, or#. - The topic filter part can use normal MQTT wildcards.
MQTT Shared Subscription Workbench
MQTT Shared Subscription Workbench
Route MQTT publications through regular subscribers, shared groups, and broker-specific worker selection policies.
animation
mqtt
protocols
mqtt5
load-balancing
Learner-ready MQTT shared subscription workbench with $share syntax validation, regular versus shared delivery comparison, shared-group worker selection policies, wildcard matching, multi-group fan-out, slow-worker backlog feedback, quick reference, source links, and desktop/mobile visual verification.
MQTT 5.0
$share syntax
Load balancing
Broker policy
MQTT Shared Subscription Workbench
Compare regular fan-out with MQTT shared subscriptions. A matching publication is delivered to every matching non-shared subscription, but to only one session inside each matching shared subscription group. The broker chooses the session; round-robin is a common policy, not a protocol guarantee.
Subscription form
$share/processors/sensors/temperature
Matching groups
1 shared group
Selected worker
worker-1
Broker output
1 copy
TryCreate $share/workers/devices/+/events/# with 3 workers, send a 6-message Publish burst, and compare Round-robin with Least backlog.
ObserveRegular fan-out delivers each message 3 times, but Shared group selects 1 worker per matching publication; Slow worker builds backlog under round-robin.
ExplainAcross 3 workers, the $share prefix groups identical Topic Filters so the broker load-balances each matching message to 1 session; worker selection remains broker-specific.
Technical boundariesThe model omits QoS redelivery after worker failure, ordering guarantees, session expiry, receive maximum, cross-node group coordination, sticky-policy collisions, ACLs, and broker persistence.
Colour keymqtt identitycurrent / primaryreference / datasuccesscautionerror / failure
1. Subscribe
2. Publish
3. Match filter
4. Pick session
5. Deliver
6. Diagnose
Configure routing
3 workers
3x processing capacity
1 message
message 1
Prefix
$share
Marks this subscription as shared instead of regular fan-out.
Share name
processors
Sessions with the same share name and topic filter form one group.
Topic filter
sensors/temperature
Standard MQTT filter syntax; wildcards still match topic levels.
Match result
matches
The published topic matches the group filter.
Publisher
Publishes message 1 to sensors/temperature.
Broker match engine
Finds one shared group with a matching filter.
Subscriber sessions
Only one session in the group receives this publication.
Shared group workers
Each worker has the same shared subscription filter. The highlighted worker receives the current message.
Routing trace
The broker first checks filter syntax, then topic matching, then chooses a session for each matching shared group.
Shared delivery: one copy to one worker
The publication matches $share/processors/sensors/temperature, so the broker sends one copy to one active session in the processors group.
Quick reference
Delivery rule
- A regular subscription gets its own matching copy.
- A shared group gets one matching copy per publication.
- Different shared groups receive independent copies.
Broker policy
- The spec defines the shared-group behavior, not a required balancing algorithm.
- Round-robin, least backlog, and sticky policies are broker choices.
- Ordering across the whole group is not the same as one subscriber seeing all messages.
Technical accuracy notes
Session, not process
The broker selects among subscribing sessions. In practice those sessions often map to worker processes or service instances, but MQTT specifies session behavior.
Matching comes first
The publication topic still has to match the topic filter after the share prefix and share name are removed. Shared subscriptions do not change MQTT topic matching rules.
QoS remains per subscription
Shared subscriptions load-balance delivery. They do not replace QoS handshakes, retained-message semantics, or application-level idempotency.