Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Routing Patterns

Headers and the Default Exchange

Route on message headers with the RabbitMQ headers exchange and x-match, understand the default exchange, and pick the right exchange type for each job.

Direct, fanout and topic exchanges all route on a single string, the routing key. Two more tools complete the picture: the headers exchange, which routes on several attributes in the message's headers table, and the default exchange, which you have already used without declaring it. This lesson explains both and ends with a decision guide for choosing between all the types.

pika code is read-only for a real broker; runnable blocks are Python stand-ins that follow the matching rules.

The headers exchange

A headers exchange ignores the routing key. Instead, each binding carries an arguments table, and the exchange compares it with the message's headers property. This is handy when routing depends on several independent attributes that do not fit naturally into one dotted string: format, language, priority class, tenant.

The special binding argument x-match chooses how the pairs combine:

  • all (default): every listed header must be present with an equal value.
  • any: at least one listed header must match.
  • all-with-x and any-with-x: like all and any, but header names starting with x- also take part in the comparison. Normally x- headers in the binding are ignored because they are reserved for broker use.

Matching is by equality of name and value; there are no ranges or wildcards. Types matter: the integer 5 does not equal the string "5".

Python
# real pika code, read-only
channel.exchange_declare("documents", exchange_type="headers", durable=True)

channel.queue_declare("pdf.reports", durable=True)
channel.queue_bind(
    queue="pdf.reports",
    exchange="documents",
    arguments={"x-match": "all", "format": "pdf", "kind": "report"},
)

channel.queue_declare("urgent.any", durable=True)
channel.queue_bind(
    queue="urgent.any",
    exchange="documents",
    arguments={"x-match": "any", "priority": "urgent", "vip": True},
)

channel.basic_publish(
    exchange="documents",
    routing_key="",                       # ignored
    body=b"...",
    properties=pika.BasicProperties(headers={"format": "pdf", "kind": "report"}),
)

A headers matcher you can test

Python x-match all, any and the x- rule (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The fourth message does not reach typed because "5" is a string, a typical type mistake.

Headers versus topic

Prefer a topic exchange when a single hierarchical key works. Headers have costs:

  • Matching is linear: each binding is tested in turn, so very large numbers of bindings are slow compared with the trie used for topic exchanges.
  • Producers must build a headers table for every message.
  • There is no hierarchy or wildcard matching.

Use headers when attributes are truly independent, optional and few in number. Many teams never need them.

The default exchange revisited

You met it in Hello World: Publish and Consume and again in Exchanges Overview. In short:

  • Name: the empty string "" (AMQP calls it amq.default in some places).
  • Type: direct.
  • Every queue is automatically bound to it with a binding key equal to the queue name.
  • You cannot bind to it, unbind from it, or delete it.

Consequently basic_publish(exchange="", routing_key="jobs") sends straight to the queue jobs. It makes the common "send directly to a named queue" case trivial and hides the exchange machinery.

When is the default exchange the right choice?

  • Replies (RPC): the reply is sent to the queue named in reply_to, a private queue of the requester.
  • Point-to-point work queues with one well-known queue.
  • Quick experiments and tests.

When should you declare your own exchange instead?

  • When several queues must receive copies (fanout or topic).
  • When producers should not need to know queue names, only the event they publish. Publishing via your own exchange lets you add consumers later without touching the publisher.
  • When you want per-exchange permissions: a user may be allowed to write to one exchange and not another, whereas writing to the default exchange can reach every queue the user has write permission on (permissions are matched by name pattern, so the default exchange needs careful rules).
Python Default exchange as an implicit direct exchange (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other exchange types you may meet

  • amq.match: a predeclared headers exchange.
  • Consistent hash exchange (plugin rabbitmq_consistent_hash_exchange): hashes the routing key (or a header) and spreads messages across its bound queues by weight. Use it to shard a stream of work while keeping all messages with the same key in the same queue, preserving per-key order.
  • Delayed message exchange (community plugin): holds messages for a delay before routing them.
  • Random exchange and Local random exchange: deliver each message to one randomly chosen bound queue.
  • Recent history exchange: replays the last N messages to new subscribers.

Plugins must be enabled on all nodes with rabbitmq-plugins enable.

Choosing an exchange type

Which exchange?

One known queue Default exchange or direct.
Everyone gets it Fanout.
Pattern of a key Topic.
Several attributes Headers.

When in doubt, topic is the most flexible starting point.

1 / 2

Quick comparison:

Type Uses Compares Typical use
default routing key queue name replies, simple queues
direct routing key equality job types, severities
fanout nothing nothing broadcasts
topic routing key wildcard pattern event streams
headers headers table equality, all/any multi-attribute routing

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a headers exchange do with the routing key?

    Headers exchanges route using the headers table and binding arguments only.
  2. 2. A binding has x-match=any with two header pairs. When does a message match?

    any means one match is enough, while all requires every listed pair to match.
  3. 3. Which statement about the default exchange is true?

    The default exchange is a nameless direct exchange with an automatic binding for each queue; you cannot change those bindings.
  4. 4. A message has the header retries="5" (a string) and a binding requires retries=5 (an integer). What happens?

    Header values are compared for equality, and a string "5" is not equal to the integer 5.

Summary

  • Headers exchanges route on the headers table, ignoring the routing key; x-match selects all, any or their -with-x variants.
  • Matching is exact equality (types matter) and linear in the number of bindings, so use headers sparingly.
  • The default exchange is a nameless direct exchange where each queue is bound by its own name.
  • Choose your own exchange when several consumers or future consumers are involved; use the default for replies and simple direct delivery.
  • Plugins add consistent-hash, delayed and other exchange types.

Next: Publisher Confirms and Returns