Topic Filters

Filters let you narrow message delivery to specific entities within a topic. Instead of receiving all updates, subscribe with filters and only get the messages you care about.

Why Filters?

Without filters, subscribing to a topic delivers every message published to it. For a dashboard showing 3 bookings out of thousands, this means receiving updates for all bookings and discarding most of them client-side.

Filters solve this at the infrastructure level. Subscribe to bookings with filters ["booking_1", "booking_2"] and only updates for those two bookings are delivered. When the user navigates to different bookings, swap filters dynamically, no resubscribe needed.

How It Works

Each filter value becomes a separate subscription at the infrastructure level, so filtering happens before messages reach your client, not by inspecting message payloads. This means zero wasted bandwidth.

No filters (wildcard, receives everything on the topic):

subscribe("bookings")

With filter, only receives matching updates:

subscribe("bookings", { filters: ["booking_1"] })

Publish targeting filtered subscribers:

publish("bookings", data, { filter: "booking_1" })

Publish without filter:

publish("bookings", data) // only wildcard subscribers receive this

Subscribe with Filters

Pass a filters array when subscribing to a topic:

import { NoLag } from '@nolag/js-sdk'

const client = NoLag('your_access_token')
await client.connect()

const room = client.setApp('dashboard').setRoom('ops')

// Subscribe with filters: only receive updates for these bookings
room.subscribe('bookings', {
  filters: ['booking_1', 'booking_2']
})

// Listen for messages (only matching filters arrive)
room.on('bookings', (data, meta) => {
  console.log('Booking update:', data)
  console.log('Filter:', meta.filter)  // e.g. 'booking_1'
})

Dynamic Filter Management

Change filters at any time without unsubscribing and resubscribing. New filters are subscribed before old ones are removed to minimize message gaps.

// Replace all filters (full swap)
room.setFilters('bookings', ['booking_3', 'booking_4'])

// Add filters to existing set
room.addFilters('bookings', ['booking_5'])
// Now active: ['booking_3', 'booking_4', 'booking_5']

// Remove specific filters
room.removeFilters('bookings', ['booking_3'])
// Now active: ['booking_4', 'booking_5']

// Remove all filters (switch to wildcard, receives everything)
room.setFilters('bookings', [])

Publishing with Filters

Specify a filter when publishing to target specific subscribers:

// Publish to a specific filter
room.emit('bookings', { status: 'confirmed' }, {
  filter: 'booking_1'
})
// Only subscribers with 'booking_1' in their filters receive this

// Publish without a filter
room.emit('bookings', { type: 'system_update' })
// Only wildcard subscribers (no filters) receive this
// Filtered subscribers do NOT receive filterless publishes

Important: Messages published without a filter are only delivered to wildcard (no-filter) subscribers. Filtered subscribers do NOT receive filterless publishes. Use a separate topic for broadcasts if needed.

Example: Real-time Dashboard

The most common use case for filters is dashboards where users view a subset of entities that update in real-time:

// Real-time dashboard: user views 3 bookings out of thousands
const room = client.setApp('dashboard').setRoom('ops')

// Subscribe only to the bookings currently visible
const visibleBookingIds = ['booking_42', 'booking_87', 'booking_153']
room.subscribe('bookings', {
  filters: visibleBookingIds
})

room.on('bookings', (data, meta) => {
  updateBookingCard(meta.filter, data)
})

// User navigates to a different page of bookings
function onPageChange(newBookingIds: string[]) {
  room.setFilters('bookings', newBookingIds)
}

// User opens a booking detail view, add it to filters
function onBookingOpen(bookingId: string) {
  room.addFilters('bookings', [bookingId])
}

// User closes a booking detail view, remove it
function onBookingClose(bookingId: string) {
  room.removeFilters('bookings', [bookingId])
}

Filter Rules

Max 100 filters per topic per connection
Filter values must not contain /, #, or + (reserved characters)
Filters are persisted, on reconnect, your filters are automatically restored
Filters work with load balancing, each filter topic uses the shared subscription group
Setting filters to an empty array switches back to wildcard mode (receives everything)

Filters vs Wildcards

Scenario	Approach
Receive all messages on a topic	Subscribe without filters (wildcard)
Receive updates for specific entities	Subscribe with filters
Change which entities to track	`setFilters` / `addFilters` / `removeFilters`
Broadcast to all subscribers	Use a separate topic (filtered subscribers won't receive filterless publishes)