# Wildcard Subscription (/sdks/kotlin/how-to/events/wildcard-subscription)



## Overview [#overview]

A **wildcard subscription** lets one subscriber match a whole family of channels with a single call, instead of wiring up a separate `subscribeToEvents` for every sub-channel and touching code each time a new one appears. It's the natural fit for monitoring, logging, or fan-in aggregation across a channel hierarchy — for example, watching every regional order channel from one place.

KubeMQ matches wildcard tokens against the channel hierarchy server-side at delivery time. `*` matches exactly one dot-separated segment, and `>` matches one or more trailing segments, so setting `channel = "orders.>"` in `subscribeToEvents` catches everything under the prefix regardless of depth. Every delivered event still carries its exact `channel`, so the collector can tell which concrete sub-channel it came from even though the subscription itself only named a pattern.

**Gotchas:** `*` matches exactly one segment — it won't reach two levels deep, so `orders.*` misses `orders.us.east`; use `>` for that. Wildcards are only valid on Events subscriptions, not on `publishEvent`/publishes or on events-store, queues, or commands/queries. And an overly broad pattern like `>` at the root will quietly pull in every channel under that prefix, including ones you didn't intend to monitor.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Kotlin SDK installed (`implementation("io.kubemq.sdk:kubemq-sdk-kotlin:1.0.1")`)

## Code [#code]

```kotlin title="WildcardSubscriptionExample.kt"
package io.kubemq.sdk.examples.events

import io.kubemq.sdk.client.KubeMQClient
import io.kubemq.sdk.pubsub.eventMessage
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.take
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

private const val ADDRESS = "localhost:50000"
private const val CLIENT_ID = "kotlin-events-wildcard-subscription"

fun main() = runBlocking {
    val client = KubeMQClient.pubSub {
        address = ADDRESS
        clientId = CLIENT_ID
    }

    client.use {
        // Subscribe with '>' wildcard -- receives from all "orders.*" channels
        val wildcardJob = launch {
            client.subscribeToEvents {
                channel = "orders.>"
            }.take(3).collect { msg ->
                println("[wildcard >] ${msg.channel}: ${String(msg.body)}")
            }
        }

        delay(500)

        // Publish to specific channels
        client.publishEvent(eventMessage {
            channel = "orders.created"
            body = "Order 1001 created".toByteArray()
        })
        client.publishEvent(eventMessage {
            channel = "orders.shipped"
            body = "Order 1002 shipped".toByteArray()
        })
        client.publishEvent(eventMessage {
            channel = "orders.delivered"
            body = "Order 1003 delivered".toByteArray()
        })

        wildcardJob.join()
        println("Done.")
    }
}
```

## How It Works [#how-it-works]

* The `>` wildcard matches all sub-channels under a prefix (e.g., `orders.>` matches `orders.created`, `orders.shipped`, etc.).
* The `msg.channel` field on received events shows the actual channel the event was published to.
* Wildcard subscriptions work with events only; the SDK rejects wildcards on all events-store operations.
* This pattern is useful for monitoring, logging, or aggregating events across related channels.

## Related [#related]

* [Basic Pub/Sub](/sdks/kotlin/tutorials/basic-pubsub)
* [Consumer Group](/sdks/kotlin/how-to/events/consumer-group)
* [Events Reference](/sdks/kotlin/reference/events)