# Wildcard Subscription (/sdks/ruby/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 `subscribe_to_events` 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 an `EventsSubscription.new(channel: 'ruby-events.wildcard.*')` catches any single-segment suffix. Every delivered event still carries its exact `channel`, so the handler 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 `send_event`/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`
* Ruby SDK installed (`gem install kubemq`)

## Code [#code]

```ruby title="main.rb"
require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')

begin
  client = KubeMQ::PubSubClient.new(address: address, client_id: 'wildcard-example')
  puts "Connected to #{address}"

  cancel = KubeMQ::CancellationToken.new

  sub = KubeMQ::PubSub::EventsSubscription.new(channel: 'ruby-events.wildcard.*')
  client.subscribe_to_events(sub, cancellation_token: cancel, on_error: ->(e) { puts "Error: #{e.message}" }) do |event|
    puts "Received on #{event.channel}: #{event.metadata}"
  end
  sleep 1

  %w[ruby-events.wildcard.a ruby-events.wildcard.b ruby-events.wildcard.c].each do |ch|
    msg = KubeMQ::PubSub::EventMessage.new(channel: ch, metadata: "hello from #{ch}", body: 'data')
    client.send_event(msg)
    puts "Sent to #{ch}"
  end

  sleep 2
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  cancel&.cancel
  client&.close
  puts 'Done'
end
```

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

* Wildcard patterns (`*` and `>`) let a single subscription match multiple channels.
* `*` matches a single segment: `ruby-events.wildcard.*` matches `ruby-events.wildcard.a` but not `ruby-events.wildcard.a.b`.
* `>` matches one or more segments: `ruby-events.>` matches all channels starting with `ruby-events.`.
* Wildcards are supported for events subscriptions only — not for events store, commands, or queries.
* Review timeouts, channel names, and client IDs before running against shared environments.

## Related [#related]

* [Pattern overview](/learn/events/getting-started)
* [Ruby SDK Reference](/sdks/ruby/reference)
* [Basic Pub/Sub](/sdks/ruby/tutorials/basic-pubsub)
* [Consumer Group](/sdks/ruby/how-to/events/consumer-group)