Subjects & wildcards

On the previous page Acme published orders.created and three services subscribed to it. That subject was a flat name. This page gives the subject some structure and lets a subscriber match a whole family of them at once.

Acme is opening regional fulfillment. Orders no longer all look the same: a US order and an EU order need to land somewhere a regional service can tell them apart. The subject is where that distinction lives.

A subject is a sequence of tokens

A subject is a string the server uses to match publishers to subscribers. You already used one: orders.created.

The . (dot) splits the subject into tokens. orders.created is two tokens, orders then created. The server treats each token as a separate unit when it matches.

That splitting turns a flat name into a hierarchy. Acme can put the region in the middle:

orders.us.created
orders.eu.created
orders.us.canceled
orders.eu.canceled

Each of those is three tokens. The first token groups them all under orders. The second token says which region. The third says what happened. The server isn't configured to know "region" means anything; the meaning lives entirely in the names Acme chose.

A few rules govern what a token may contain.

Subjects are case-sensitive. Orders.created and orders.created are two different subjects. A publisher to one won't reach a subscriber on the other.

Tokens are split by single dots only. Spaces, tabs, and line breaks aren't allowed anywhere in a subject. Stick to letters, digits, -, and _ inside a token and you'll never be surprised.

Subjects cost almost nothing to create

Acme just invented four new subjects without telling the server first — that's allowed, and it costs almost nothing. The interest graph from the previous page holds an entry for a subject only once something subscribes to it, so a subject nobody listens to has no presence on the server at all. You never declare or clean up subjects, and a system can use millions of them without slowing the server down, because matching walks the token tree rather than scanning every subscription.

Wildcards: subscribe to many subjects at once

A publisher always names one full subject. nats pub to orders.*.created isn't "publish to every region": it would publish to the literal subject containing a *, which nobody wants. Wildcards are a subscriber-only tool.

A wildcard is a token in a subscription that matches more than one literal subject. NATS has exactly two of them, and they differ in how many tokens they match.

The single-token wildcard *

The single-token wildcard * matches exactly one token — not zero, not two.

Acme wants one analytics view of created orders across every region. Instead of subscribing to orders.us.created and orders.eu.created separately, it subscribes once to orders.*.created:

CLI

#!/bin/bash

# Regional analytics: catch created orders from every region with one
# subscription. The single-token wildcard * matches exactly one token in
# the region position, so orders.us.created and orders.eu.created both
# match, while orders.created and orders.us.west.created do not.
nats sub "orders.*.created"

JavaScript/TypeScript

// Regional analytics: one subscription catches created orders from every
// region. The single-token wildcard * matches exactly one token, so both
// orders.us.created and orders.eu.created match, while orders.created and
// orders.us.west.created do not.
const sub = nc.subscribe("orders.*.created");
for await (const msg of sub) {
  console.log(`analytics: new order on ${msg.subject}`);
}

Go

// Regional analytics: one subscription catches created orders from every
// region. The single-token wildcard * matches exactly one token, so
// orders.us.created and orders.eu.created both match, while orders.created
// and orders.us.west.created do not.
nc.Subscribe("orders.*.created", func(m *nats.Msg) {
	fmt.Printf("analytics: new order on %s\n", m.Subject)
})

Python

# Regional analytics: one subscription catches created orders from every
# region. The single-token wildcard * matches exactly one token, so both
# orders.us.created and orders.eu.created match, while orders.created and
# orders.us.west.created do not.
async with await client.subscribe("orders.*.created") as subscription:
    async for message in subscription:
        print(f"analytics: new order on {message.subject}")

Java

// Regional analytics: one subscription catches created orders from every
// region. The single-token wildcard * matches exactly one token, so both
// orders.us.created and orders.eu.created match, while orders.created and
// orders.us.west.created do not.
nc.createDispatcher(msg ->
    System.out.println("analytics: new order on " + msg.getSubject())
).subscribe("orders.*.created");

Rust

// Regional analytics: one subscription catches created orders from every
// region. The single-token wildcard * matches exactly one token, so both
// orders.us.created and orders.eu.created match, while orders.created and
// orders.us.west.created do not.
let mut sub = client.subscribe("orders.*.created").await?;
while let Some(msg) = sub.next().await {
    println!("analytics: new order on {}", msg.subject);
}

C#/.NET

// Regional analytics: one subscription catches created orders from every
// region. The single-token wildcard * matches exactly one token, so both
// orders.us.created and orders.eu.created match, while orders.created and
// orders.us.west.created do not.
await foreach (var msg in client.SubscribeAsync<Order>("orders.*.created"))
{
    output.WriteLine($"analytics: new order on {msg.Subject}");
}

C

// Regional analytics: one subscription catches created orders from every
// region. The single-token wildcard * matches exactly one token, so
// orders.us.created and orders.eu.created both match, while orders.created
// and orders.us.west.created do not.
static void
onOrder(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)
{
    printf("analytics: new order on %s\n", natsMsg_GetSubject(msg));

    natsMsg_Destroy(msg);
}
    if (s == NATS_OK)
        s = natsConnection_Subscribe(&sub, conn, "orders.*.created",
                                     onOrder, NULL);

The * sits in the region position. Walk through what it catches:

• orders.us.created matches: * takes the single token us.
• orders.eu.created matches: * takes the single token eu.
• orders.created does not match: there's no token in the region position, and * needs exactly one.
• orders.us.west.created does not match: two tokens sit where * allows only one.

The position of * is fixed; the token in it is free. You can also use more than one: orders.*.* matches any three-token subject under orders, with both middle and last tokens free.

The multi-token wildcard >

The multi-token wildcard > matches one or more tokens, and it must be the last token in the pattern.

Acme is adding an audit service that wants every order message, at every depth, regardless of region or action. One subscription covers it:

CLI

#!/bin/bash

# Audit service: catch every order message at any depth. The multi-token
# wildcard > matches one or more tokens and must be the last token, so
# orders.> matches orders.created, orders.us.created, and
# orders.us.west.created alike.
nats sub "orders.>"

JavaScript/TypeScript

// Audit service: catch every order message at any depth. The multi-token
// wildcard > matches one or more tokens and must be the last token, so
// orders.> matches orders.created, orders.us.created, and
// orders.us.west.created alike.
const sub = nc.subscribe("orders.>");
for await (const msg of sub) {
  console.log(`audit: ${msg.subject}`);
}

Go

// Audit service: catch every order message at any depth. The multi-token
// wildcard > matches one or more tokens and must be the last token, so
// orders.> matches orders.created, orders.us.created, and
// orders.us.west.created alike.
nc.Subscribe("orders.>", func(m *nats.Msg) {
	fmt.Printf("audit: %s\n", m.Subject)
})

Python

# Audit service: catch every order message at any depth. The multi-token
# wildcard > matches one or more tokens and must be the last token, so
# orders.> matches orders.created, orders.us.created, and
# orders.us.west.created alike.
async with await client.subscribe("orders.>") as subscription:
    async for message in subscription:
        print(f"audit: {message.subject}")

Java

// Audit service: catch every order message at any depth. The multi-token
// wildcard > matches one or more tokens and must be the last token, so
// orders.> matches orders.created, orders.us.created, and
// orders.us.west.created alike.
nc.createDispatcher(msg ->
    System.out.println("audit: " + msg.getSubject())
).subscribe("orders.>");

Rust

// Audit service: catch every order message at any depth. The multi-token
// wildcard > matches one or more tokens and must be the last token, so
// orders.> matches orders.created, orders.us.created, and
// orders.us.west.created alike.
let mut sub = client.subscribe("orders.>").await?;
while let Some(msg) = sub.next().await {
    println!("audit: {}", msg.subject);
}

C#/.NET

// Audit service: catch every order message at any depth. The multi-token
// wildcard > matches one or more tokens and must be the last token, so
// orders.> matches orders.created, orders.us.created, and
// orders.us.west.created alike.
await foreach (var msg in client.SubscribeAsync<Order>("orders.>"))
{
    output.WriteLine($"audit: {msg.Subject}");
}

C

// Audit service: catch every order message at any depth. The multi-token
// wildcard > matches one or more tokens and must be the last token, so
// orders.> matches orders.created, orders.us.created, and
// orders.us.west.created alike.
static void
onOrder(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)
{
    printf("audit: %s\n", natsMsg_GetSubject(msg));

    natsMsg_Destroy(msg);
}
    if (s == NATS_OK)
        s = natsConnection_Subscribe(&sub, conn, "orders.>", onOrder, NULL);

orders.> reaches the entire hierarchy under orders:

• orders.created matches: > takes the one token created.
• orders.us.created matches: > takes the two tokens us.created.
• orders.us.west.created matches: > takes all three remaining tokens.
• orders does not match: > needs at least one token after the prefix.

Because > matches a token and everything after it, it only makes sense at the end. orders.>.created is invalid: the server rejects the subscription with an Invalid Subject error. There's no way to anchor a tail wildcard in the middle and still know where it stops.

This is the difference to keep: * is a placeholder for one token in a known shape; > is "everything from here down."

A wildcard subscriber behaves like any subscriber

A wildcard doesn't change the delivery model from the last page. It changes which subjects count as a match, nothing else.

The audit service on orders.> is just another interested subscriber. When Acme publishes orders.us.created, every matching subscriber gets its own copy: the warehouse on orders.created does not (different subject now), the regional analytics on orders.*.created does, and the audit service on orders.> does. The server fans one publish out to all of them. Delivery is still at-most-once: a wildcard lets a service that joins now see everything published from now on, not what it missed before joining. Capturing that backlog is what JetStream adds.

Reserved prefixes to avoid

Acme can name subjects almost anything, but two prefixes are reserved.

Subjects beginning with $ belong to the server and its subsystems: $SYS for system events, and $JS, $KV, $O, and $SRV for the JetStream, Key-Value, Object-Store, and Services subsystems. Don't publish application messages under $.

The _INBOX prefix is reserved for reply subjects that clients generate automatically. You don't pick _INBOX names yourself, and you don't publish business messages there. The next page, on request-reply, shows exactly what _INBOX is for.

Try it in two terminals

With nats-server running, watch a wildcard catch messages it was never told about by name:

# Terminal 1 — the audit service: every order message, any depth
nats sub "orders.>"

# Terminal 2 — publish to two regions and a flat subject
nats pub orders.us.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
nats pub orders.eu.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
nats pub orders.shipped    '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

All three arrive in Terminal 1. Now restart Terminal 1 with nats sub "orders.*.created" and re-run Terminal 2: only the two *.created messages arrive; orders.shipped no longer matches.

Pitfalls

> only works as the last token. Use * for a free token in the middle: subscribe to orders.*.created, not the invalid orders.>.created, which the server rejects.

Publishers can't publish "to a wildcard." Wildcards are a subscriber-only tool. A publisher always names one fully-qualified subject. The trap is that publishing to orders.*.created doesn't produce an error: the * is taken as a literal character, so the message lands on the odd literal subject orders.*.created. A service subscribed to the exact subject orders.us.created never sees it, while wildcard subscribers like the regional analytics on orders.*.created and the audit service on orders.> do get it — a subscription's * matches any single token, including a literal * — which makes the mistake confusing to debug. Publish the real subject (orders.us.created); reserve * and > for nats sub and the subscribe call in your client.

An over-broad orders.> pulls more than you want. It's tempting to subscribe to orders.> and filter in code, but that subscriber then receives every order message at every depth, for all regions and actions, including subjects created later. Subscribe to the narrowest pattern that covers your need: orders.*.created for regional new-order analytics, the exact subject for a single concern. Narrow interest keeps unwanted traffic off the wire entirely, rather than having your code discard it after delivery.

Whitespace is never allowed in a subject. A token can't contain a space, tab, or line break: on the wire, a space separates the subject from the reply subject and byte count, so a space inside a subject would be read as a boundary. The CLI and most clients catch this before sending — publishing to orders.us created fails with nats: invalid subject, and nothing is sent. A client that skips the check (nats.py's publish does) writes the space straight into the PUB line, and the server silently misroutes: orders.us becomes the subject and created a reply subject. Don't rely on the check; keep spaces out of the subject:

CLI

#!/bin/bash

# A subject token can't contain whitespace. On the wire, a space separates the
# subject from the reply subject and byte count, so a modern client rejects the
# subject before anything is sent. This publish therefore FAILS with
#   nats: error: nats: invalid subject
# and exits non-zero -- the message never reaches the server.
nats pub "orders.us created" '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

# (An older client -- nats.go before v1.48.0 -- or a raw-protocol writer skips
# this check and would instead misroute silently: the server would read
# "orders.us" as the subject and "created" as a reply subject.)

# The fix is one token per dot, no spaces: orders.us.created
nats pub "orders.us.created" '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

C

// A subject token can't contain whitespace: on the wire, a space
// separates the subject from the reply subject and byte count. The C
// client's publish skips the check, so this call does NOT fail: the
// space goes straight into the PUB line and the server silently
// misroutes: "orders.us" becomes the subject and "created" a reply
// subject. Nobody subscribed to orders.us.created ever sees it.
const char *order = "{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
                    "\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}";

s = natsConnection_PublishString(conn, "orders.us created", order);
printf("publish with a space returned: %s\n", natsStatus_GetText(s));

// Don't rely on a client-side check; keep spaces out of the subject.
// The fix is one token per dot: orders.us.created.
if (s == NATS_OK)
    s = natsConnection_PublishString(conn, "orders.us.created", order);

Where you are

Acme's order traffic now has a shape:

• Orders publish to structured subjects: orders.created, orders.us.created, orders.eu.created, and so on.
• Regional analytics subscribes to orders.*.created to catch every region's new orders with one subscription.
• An audit service subscribes to orders.> to catch the whole hierarchy.

Subjects address messages; wildcards let one subscriber match a family of them. That's the addressing layer everything else in core NATS uses.

What's next

So far every message flows one way: a publisher sends, subscribers receive, and nobody sends a reply back. The next page, Request-reply, adds a reply path: Acme builds an inventory service that answers a question on orders.inventory.check, using a reserved _INBOX subject you just met.

See also

• Core Concepts → Subjects — the short overview of tokens and wildcards.
• Learn → Security — granting or denying access per subject and wildcard.
• Learn → Super-clusters — how subject interest propagates across servers and regions.