Topics and wildcards

Topics are the addressing system in MQTT. Use this guide to learn how to design topic hierarchies and use + and # wildcards so a single subscription can cover many publishers.

What is a topic?

A topic is a UTF-8 string that acts as a channel for messages. Publishers send messages to topics; subscribers receive messages from topics they've subscribed to.

Topic-based routing

Publisher

publish(agents/agent-001/state)

Broker

Routes to matching subscriptions

deliver

Subscriber

Topic structure

Topics use / as a level separator to create hierarchies:

agents/team-alpha/agent-001/state/load
   |        |          |       |     |
   |        |          |       |     L Field
   |        |          |       L Category
   |        |          L Agent ID
   |        L Group
   L Category

Topic naming rules

Rule	Example
Case-sensitive	`Agents/State` is not the same as `agents/state`
UTF-8 strings	Most characters allowed
No spaces (recommended)	Use `team-alpha` not `team alpha`
Leading `/` allowed but creates empty level	`/agents/state` has 3 levels, first is empty

Best practices

Good topic design:
  agents/{agent-id}/state
  users/{user-id}/notifications
  teams/{team}/agents/{agent-id}/inbox/{thread-id}

Poor topic design:
  data                    (too vague)
  a/b/c/d/e/f/g/h/i      (cryptic)
  my topic with spaces    (spaces cause issues)

Wildcards

Wildcards let you subscribe to multiple topics with a single subscription.

Single-level wildcard: `+`

Matches exactly one level in the topic hierarchy.

Subscription: agents/+/state

Matches:
  agents/agent-001/state
  agents/agent-002/state
  agents/abc123/state

Does NOT match:
  agents/state                        (missing a level)
  agents/team-a/agent-001/state       (too many levels)

Use cases:

# Subscribe to state from any agent
agents/+/state

# Subscribe to any field for agent-001
agents/agent-001/+

# Any agent, any field
agents/+/+

Multi-level wildcard: `#`

Matches zero or more levels. Must be the last character in the subscription.

Subscription: agents/#

Matches:
  agents
  agents/state
  agents/agent-001/state
  agents/team-a/agent-001/inbox/task-42

Does NOT match:
  rooms/room-9   (different root)

Use cases:

# Everything under agents
agents/#

# Everything under a specific agent
agents/agent-001/#

# All topics (use with caution)
#

Subscribing to # receives ALL messages in your organization. This can overwhelm clients and incur costs. Use specific subscriptions.

Combining wildcards

You can use multiple + wildcards and one #:

# Any team, any agent, all fields
teams/+/agents/+/#

Matches:
  teams/alpha/agents/001/state
  teams/alpha/agents/002/inbox
  teams/beta/agents/lead/logs/debug

Publishing vs. subscribing

Operation	Wildcards allowed?
Publish	No, must specify exact topic
Subscribe	Yes, can use `+` and `#`

// Publishing - exact topic required
client.publish('agents/agent-001/state', '{"status":"online"}');

// Subscribing - wildcards allowed
client.subscribe('agents/+/state');
client.subscribe('agents/#');

Topic design patterns

Agent-centric

agents/{agent-id}/state
agents/{agent-id}/inbox
agents/{agent-id}/logs

Example:
  agents/agent-001/state  ->  {"status":"online","load":0.42}
  agents/agent-001/inbox  ->  {"task":"summarize-thread"}

Group-based

{group}/{subgroup}/.../field

Example:
  teams/alpha/agents/001/state
  rooms/room-9/presence

User-centric

users/{user-id}/notifications
users/{user-id}/presence
users/{user-id}/messages/inbox

Example:
  users/user-123/notifications  ->  {"type":"alert", ...}

Action-based

{resource}/commands
{resource}/events
{resource}/requests
{resource}/responses

Example:
  agents/agent-001/commands  ->  {"action":"pause"}
  agents/agent-001/events    ->  {"state":"paused"}

Reserved topics

Some topics have special meaning in MQTT:

Topic pattern	Purpose
`$SYS/#`	Broker statistics (read-only)
`$share/{group}/topic`	Shared subscriptions

Topics starting with $ are typically reserved for system use. CloudSignal may use these for internal features.

Performance considerations

Topic specificity

More specific subscriptions equal better performance:

Better:  agents/agent-001/state
Good:    agents/+/state
Avoid:   agents/#  (if you only need state)
Worst:   #

Topic length

Keep topics reasonably short. Long topics increase bandwidth slightly. Balance descriptive against concise:

Good:    agents/agent-001/state
Too long: organization/acme-corp/teams/alpha/cohorts/onboarding/agents/agent-001/state/snapshots/current/value

Next steps

QoS levels - Delivery guarantees
Retained messages - Persist last value
ACL topic patterns - Security for topics

On this page