Topic Trees

Every IBM MQ queue manager that runs publish/subscribe maintains a topic tree: an in-memory and repository-backed hierarchy of topic strings. When an application publishes to healthcare/claim/adjudicated, the pub/sub engine walks or creates nodes for healthcare, then claim, then adjudicated. Subscriptions registered at healthcare/claim/# or healthcare/+/adjudicated are evaluated against that same tree structure—not against a flat list of queue names. Beginners who treat topic strings as arbitrary labels often design subscriptions that never fire: the publish path has four levels while the subscription pattern only allows three. This tutorial explains what the tree is, how nodes appear, how parents and children relate to wildcards, how topic objects anchor branches, how cluster and administrative topics attach to the tree, monitoring commands, capacity and authority implications, and design practices that keep enterprise event catalogs maintainable.

Tree Structure: Parents, Children, and Leaves

Think of the topic tree like a file system without files at folders—only path names. The root is implicit. Each segment after a slash is a child of the previous segment. finance is a parent of finance/payment; finance/payment is a parent of finance/payment/posted. A publication always targets a leaf path (the full string), but subscriptions may attach at any node: exact leaf finance/payment/posted, single-level wildcard finance/+/posted, or multi-level finance/payment/#. Authority profiles and PUB/SUB permissions are often granted at a parent node so all children inherit consistent rules on platforms that support subtree authority—verify OAM behavior on your operating system.

How Nodes Enter the Tree

Nodes become active when traffic demands them. The first publish to logistics/shipment/dispatched creates the chain of nodes if they did not exist. Likewise, DEFINE SUB with TOPICSTR('logistics/shipment/#') registers interest and materializes subscription state tied to that branch. Pre-creating DEFINE TOPIC objects does not by itself move messages—it documents branches, sets TOPTYPE and scope attributes, and gives administrators DISPLAY TOPIC handles before applications go live. In regulated environments, change control prefers TOPIC objects on paper first, then application cutover, so the tree does not sprawl with ad hoc strings like TEAM42/BUGFIX/TRY3.

Wildcards Walk the Tree

The single-level wildcard + occupies exactly one segment position. Pattern retail/+/shipped matches retail/uk/shipped and retail/us/shipped but not retail/uk/london/shipped because london is a second variable level where only one + was allowed. The multi-level wildcard # must appear as the last character of the pattern (in standard IBM MQ topic syntax) and matches zero or more trailing segments. Pattern retail/# matches retail/uk/shipped and retail/shipped alike. Designing subscriptions is the art of placing + and # at the correct depth in the tree—too broad and you flood downstream apps with unrelated events; too narrow and you maintain hundreds of nearly duplicate subscriptions.

1
2
3
4
5
6
7
8
9
10
11
* Parent branch object (optional but recommended)
DEFINE TOPIC('RETAIL.BRANCH') TOPSTR('retail') TOPTYPE(LOCAL) +
  DESCR('Retail domain root')
* Publications (application or amqspub sample)
* Topic string: retail/uk/order/created
* Subscriptions:
DEFINE SUB('RETAIL.UK.ORDERS') TOPICSTR('retail/uk/order/#') +
  DESTQL('RETAIL.UK.ORD.SUB') DESTQMGR('QM1')
DEFINE SUB('RETAIL.ALL.SHIPPED') TOPICSTR('retail/+/shipped') +
  DESTQL('RETAIL.SHIP.SUB') DESTQMGR('QM1')
DISPLAY SUB('*') TOPICSTR

Topic Objects as Tree Anchors

Topic objects map friendly names to TOPSTR paths. A tree anchored by FINANCE.ROOT with TOPSTR('finance') signals to developers that all finance strings live under that prefix. Cluster topics (TOPTYPE CLUS) extend the tree across queue managers by advertising branches in the cluster repository—see the clustered topics tutorial. Alias topics graft one path onto another without duplicating publishers. The tree is the live structure; objects are the catalog and policy layer on top.

Explainer: Building Floors in a Office Tower

The topic tree is a office tower directory. finance is a floor, payment is a wing, posted is a room number. A visitor (publisher) must announce the full room. Listeners (subscriptions) can wait at a specific room, at any room on a wing ( + ), or anywhere on the floor (#). If you wait in the wrong wing, you never hear the announcement even though the speaker did talk.

Monitoring and Troubleshooting

1. Confirm publish string in application log character-for-character—including case on case-sensitive platforms.
2. DISPLAY SUB for pattern and DEST; verify DURSUB and scope if messages missing after restart.
3. DISPLAY TOPICSTATUS or TPSTATUS (per your release) to see active pub/sub nodes and publishers.
4. Check authority at parent prefix if puts succeed but subs never get copies.
5. For cluster estates, verify cluster topic definitions propagated—local tree alone is insufficient for remote fan-out.

Design Guidelines for Enterprise Trees

• Standardize depth: domain/entity/event/version is clearer than flat EVENT codes.
• Separate test and prod prefixes: test/finance/... versus prod/finance/...
• Document which levels may use # for application teams—broad # subscriptions multiply message volume.
• Place administrative topic parents before leaves; avoid hundreds of orphan leaves without a branch object.
• Review retained publications at branch level—retain on a high # pattern has different reach than retain on a leaf.

Topic Tree vs Point-to-Point Names

Queue names are not hierarchical for routing. Opening PAYMENT.IN does not imply PAYMENT.IN.ERROR. Topic strings inherit prefix semantics in the tree. Migrating from queues to topics requires teaching teams that string design is part of interface contract, not an afterthought. API gateways and JSON schemas should list allowed topic prefixes the same way WSDL lists operations.

Capacity and Fan-Out

The tree itself is lightweight compared to message duplication. A publish that matches fifty subscriptions creates fifty puts. A subscription at prod/# on a busy parent can pull thousands of messages per minute to one DEST queue—CURDEPTH and MAXDEPTH on subscriber queues become the bottleneck, not the tree nodes. Monitor subscriber queue depth alarms separately from topic object counts.

Explain Like I'm Five: Topic Trees

The topic tree is like folders on a computer. You can put a note in Documents/School/Homework.txt. Your friend can say “give me everything in the School folder” or “only Homework files.” IBM MQ uses slashes instead of folders, but the idea of big folders and little folders is the same.

Practice Exercises

Exercise 1

Draw a tree for retail/uk/order/created and retail/us/order/created. Mark where retail/+/order/created and retail/# attach.

Exercise 2

Write why retail/+/created does not match retail/uk/store/order/created.

Exercise 3

List three DISPLAY commands you would run when a subscriber receives zero messages but publish returns success.

Frequently Asked Questions

Test Your Knowledge