A topic filter is the rule that decides which messages a Service Bus subscription receives from a shared topic. Publishers send one message to the topic, and each subscription uses filters to decide whether that message belongs in its queue-like stream. A billing system might receive only invoice events, while a fulfillment system receives only shipment events. Filters keep subscribers from wasting work on irrelevant messages, but they must match the actual message properties publishers send. The filter becomes part of the integration contract. The filter becomes part of the integration contract.
Service Bus filter, subscription filter, topic subscription rule, SQL filter rule, correlation filter rule
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-28
Microsoft Learn
A topic filter is a Service Bus subscription rule that selects which messages from a topic are delivered to a subscription. Filters can match message properties with SQL expressions or correlation values, and matching rules can optionally apply actions before delivery.
In Azure architecture, topic filters live inside Azure Service Bus topics and subscriptions. The topic accepts messages from publishers, subscriptions hold copies for consumers, and rules on each subscription evaluate message properties. Filters can be SQL filters, correlation filters, or true filters, depending on the matching need. They sit in the messaging data plane but are managed through ARM, Azure CLI, SDKs, and the portal. Topic filters interact with dead-letter queues, duplicate detection, sessions, transactions, message TTL, managed identity, private endpoints, and diagnostic logs. It is configuration, routing logic, and operational evidence. It is configuration, routing logic, and operational evidence.
Why it matters
Topic filters matter because they decide which subscribers receive which messages. A bad filter can starve a consumer, send private messages to the wrong workflow, duplicate work across teams, or hide an outage until a downstream queue is empty. Filters also let one topic support multiple business processes without forcing every consumer to inspect and discard irrelevant messages. For architects, the filter becomes part of the integration contract. For operators, exact rule evidence is often the fastest path to explaining why a message did or did not arrive. Clear evidence keeps design reviews practical, accountable, and tied to business risk instead of guesswork.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In the Azure portal, a Service Bus subscription Rules page shows SQL filters, correlation filters, rule names, optional actions, and default rules for message selection.
Signal 02
In Azure CLI output, subscription rule lists show each rule attached to a topic subscription, including filter type, SQL expression details, and rule names for release records.
Signal 03
In consumer telemetry, empty subscriptions, unexpected message types, duplicate processing, delivery delays, or dead-letter spikes point back to filter conditions and publisher properties during operations.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Route order events to tax, fulfillment, fraud, and analytics subscribers without making every consumer inspect every order message.
Keep regulated or tenant-specific event types out of subscriptions that are not approved to process that data.
Migrate from point-to-point queues to publish-subscribe messaging while preserving each application’s routing contract.
Use correlation filters for exact event-type or tenant matches where a SQL expression would be unnecessary complexity.
Troubleshoot missing or duplicate messages by comparing publisher properties with the active rules on each subscription.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Airport baggage platform routes only relevant events
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
An airport operations team used one Service Bus topic for baggage events, but every subsystem received every message and several consumers fell behind during holiday peaks.
🎯Business/Technical Objectives
Route scan, load, transfer, and exception events to only the systems that need them.
Reduce consumer backlog without adding unnecessary compute.
Create a safe rollout path for new baggage-event versions.
Give operators a fast way to prove why an event reached a subscription.
✅Solution Using Topic filter
Architects defined application properties for eventType, terminal, carrierCode, and schemaVersion. Each subscription received a small set of topic filters tied to its operational role: carousel displays, transfer coordination, lost-bag investigation, and analytics. The team removed the default catch-all rule from filtered subscriptions and used correlation filters for exact event-type matches. CLI exports captured every rule before rollout, and canary events verified each subscription after deployment. Azure Monitor alerts watched active-message counts and dead-letter growth so filter mistakes would surface before baggage desks were flooded with calls.
📈Results & Business Impact
Consumer backlog during peak departure banks dropped 58% without adding worker nodes.
Carousel display services stopped processing four irrelevant event types, cutting Function executions by 46%.
Schema-version filters allowed a new scanner format to run in parallel for two weeks.
Incident triage for missing events fell from 45 minutes to under 10 minutes using rule exports.
💡Key Takeaway for Glossary Readers
Topic filters keep publish-subscribe systems useful by turning one shared event stream into precise, observable delivery contracts.
Case study 02
Smart factory isolates maintenance alerts from production telemetry
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A smart factory sent machine telemetry and maintenance events through a shared Service Bus topic, causing maintenance workflows to process high-volume sensor messages they did not need.
🎯Business/Technical Objectives
Deliver only maintenance-worthy events to work-order automation.
Keep raw production telemetry available for analytics without slowing technicians.
Avoid duplicate work orders when several alert rules match.
Document routing behavior for plant engineers and cloud operators.
✅Solution Using Topic filter
The integration team standardized message properties for eventClass, assetLine, severity, and ruleVersion. Maintenance subscriptions used SQL filters for severity and eventClass, while analytics subscriptions accepted broader telemetry. Engineers removed overlapping rules that created duplicate messages and replaced them with one explicit maintenance-alert rule per line. CLI scripts listed and showed rules during every release, then saved JSON exports in the deployment artifact. A small canary publisher sent sample events for each line after changes, proving the right subscription received the alert while analytics still stored the full stream. Operators also replayed validation messages before shift handoffs. Operators replayed sample events before each production rule update. Factory operators received rule-change evidence immediately. Operators also kept a rollback file with the previous rules. Operators documented rollback commands.
📈Results & Business Impact
Duplicate maintenance work orders fell from 126 per week to fewer than 8.
Maintenance workflow executions dropped 39% because sensor-only telemetry no longer triggered them.
Technician response time to critical alerts improved by 18 minutes on average.
Plant engineers could review routing rules in plain JSON instead of relying on tribal knowledge.
💡Key Takeaway for Glossary Readers
A focused topic filter prevents high-volume telemetry from drowning the operational events that actually require action.
Case study 03
University integration hub protects student-data routing
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A university integration hub published enrollment, housing, and billing events to one topic, but downstream teams needed strict separation of data they were allowed to process.
🎯Business/Technical Objectives
Prevent housing systems from receiving billing-only events.
Let advising applications receive enrollment changes without payment details.
Support new event versions during semester registration without breaking consumers.
Create audit-ready evidence for data governance reviews.
✅Solution Using Topic filter
The platform group created a message-property standard that separated domain, eventName, dataClass, and schemaVersion. Subscription rules matched those properties instead of parsing message bodies. Housing, advising, and billing consumers received distinct filters, and the team reviewed each expression with data stewards before deployment. Azure CLI exports became part of the monthly access review, showing rule names and expressions for every subscription. The group also added canary events with test student IDs, then verified that only approved subscriptions received each event type. Dead-letter alerts caught one publisher that omitted the required dataClass property. Support staff also reviewed sample payloads before each registration window. Integration owners reviewed filtered messages during every enrollment cycle. The integration team reviewed samples before rollout. Data stewards reviewed those exports before registration week. Operators documented rollback commands.
📈Results & Business Impact
Unauthorized domain crossover in test canaries dropped to zero before production registration week.
Consumer teams reduced custom in-code filtering by 65%.
A schema-version migration ran for 30 days with no missed advising events.
Monthly data-routing review time fell from two days to four hours using CLI rule exports.
💡Key Takeaway for Glossary Readers
Topic filters are not just convenience; they are a governance control for deciding which subscribers receive which business events.
Why use Azure CLI for this?
Azure CLI is useful for topic filters because rule state is easy to misread in the portal during incidents. As a senior Azure engineer, I want a command that lists every rule on a subscription, shows the exact SQL or correlation expression, and exports it before a change. CLI makes filter review repeatable across dev, test, and production namespaces. It also helps automate rule creation during environment builds so teams do not rely on manual clicks. During message-routing incidents, CLI output provides evidence for whether the publisher, topic, subscription, or filter rule caused the missing messages. It also makes emergency rollback a copied command instead of memory. Auditable rules prevent guesswork. It also supports automated rule snapshots before risky release windows.
CLI use cases
List all rules on a subscription before changing message-routing behavior.
Show one rule to capture its SQL expression, correlation properties, and action settings for a change ticket.
Create a new filtered rule during environment provisioning instead of relying on manual portal steps.
Delete the default catch-all rule when a subscription should receive only explicitly selected event types.
Inspect subscription settings and message counts while deciding whether a routing problem is filter-related.
Before you run CLI
Confirm the tenant, subscription, resource group, namespace, topic, and subscription names; Service Bus names are easy to mix between environments.
Export existing rules before create or delete operations because filter changes can immediately alter business routing.
Verify that publishers actually set the message properties referenced by the filter expression.
Check whether the default rule still exists before assuming a subscription is narrowly filtered.
Use read-only commands first in production and schedule mutating rule changes through normal release approval.
What output tells you
Rule lists show whether a subscription has one intended filter, several overlapping filters, or a default catch-all rule.
Rule details reveal the filter type, SQL expression, correlation fields, and any action applied to matching messages.
Subscription output shows lock duration, dead-letter behavior, message TTL, and counts that affect troubleshooting.
Resource group and namespace fields confirm you are reviewing the environment that the publisher and consumer actually use.
JSON exports provide before-and-after evidence when routing changes must be audited or rolled back.
Mapped Azure CLI commands
Topic filter CLI commands
direct
az servicebus topic subscription rule list --resource-group <resource-group> --namespace-name <namespace> --topic-name <topic> --subscription-name <subscription> --output table
az servicebus topic subscription rulediscoverIntegration
az servicebus topic subscription rule show --resource-group <resource-group> --namespace-name <namespace> --topic-name <topic> --subscription-name <subscription> --name <rule> --output json
az servicebus topic subscription rulediscoverIntegration
az servicebus topic subscription ruleremoveIntegration
az servicebus topic subscription show --resource-group <resource-group> --namespace-name <namespace> --topic-name <topic> --name <subscription> --output json
az servicebus topic subscriptiondiscoverIntegration
Architecture context
Architecturally, a topic filter belongs to the integration contract between publishers and subscribers. I design it only after naming the event types, required application properties, versioning strategy, and ownership of each subscription. Filters should be simple enough for operators to reason about under pressure. SQL filters are flexible, but correlation filters can be faster and clearer for exact property matches. Strong designs avoid overlapping rules unless duplicates are intentional, document the default rule, and include dead-letter monitoring. When event schemas evolve, filter changes should move through the same release process as code because they change business routing. That choice should be intentional, not inherited accidentally. This keeps routing flexible as business domains evolve. Design rule ownership early. This keeps routing flexible as business domains evolve. I also document how publishers test those required properties. I also test sample events during deployment.
Security
Security impact is indirect but important. Topic filters do not replace authentication, authorization, or encryption, but they can influence which subscribers receive sensitive events. A broad SQL filter may route payroll, health, or customer data to a workflow that should not process it. Teams should protect rule-management permissions with least privilege, review changes through infrastructure code, and audit management-plane updates. Message properties used for filtering should not expose secrets. Sensitive routing rules deserve the same review as application authorization because they affect data flow. Keep ownership, audit trails, approval paths, and emergency access documented before production changes. Keep ownership, audit trails, approval paths, and emergency access documented before production changes.
Cost
Cost impact is usually indirect. Filters reduce downstream compute by sending only relevant messages to each subscription, but poor filters can increase fan-out, duplicate processing, storage retention, dead-letter investigation, and consumer scale. A single topic with many broad rules may cause more subscribers to wake up than necessary. FinOps reviews should include message volume by subscription, dead-letter counts, idle consumers, and unused rules after migrations. Fixing noisy filters is often cheaper than scaling every consumer or adding more namespace capacity. Review ownership, idle usage, scale assumptions, chargeback signals, and retention behavior before expanding capacity. Review ownership, idle usage, scale assumptions, chargeback signals, and retention behavior before expanding capacity.
Reliability
Reliability depends on filters matching the message contract consistently. If publishers rename a property, change casing, alter types, or stop sending a field, subscriptions can silently stop receiving messages. If filters are too broad, multiple consumers may process work that belongs to one workflow. Reliable designs version message contracts, test positive and negative examples, preserve default-rule behavior intentionally, and monitor subscription backlog by rule outcome where possible. Before high-volume releases, teams should replay sample messages and verify that each subscription receives exactly the intended traffic. Test normal operation, degraded behavior, rollback steps, and dependency failure before production changes. Test normal operation, degraded behavior, rollback steps, and dependency failure before production changes.
Performance
Performance impact comes from message selection and downstream fan-out. Simple filters with clear properties help consumers receive only useful work and keep backlog manageable. Complex or broad rules can increase processing, duplicate deliveries across subscriptions, and troubleshooting time when volume rises. Publishers should set stable typed properties instead of forcing consumers to parse message bodies. Load tests should include realistic message volume, rule count, and property distribution. When latency matters, keep filter predicates simple, monitor subscription backlog, and avoid using rules as hidden business logic. Benchmark realistic load, dependency latency, concurrency limits, diagnostic query speed, retry behavior, and rollback impact before declaring the design ready.
Operations
Operators manage topic filters by listing subscription rules, reviewing SQL or correlation expressions, comparing infrastructure code with live state, and testing sample messages. During incidents, they check whether messages reached the topic, matched the intended subscription, were dead-lettered, or were ignored because a property was missing. Change records should include the old rule, new rule, example matching messages, example nonmatching messages, and rollback command. Operators also reconcile emergency portal edits back into code so future deployments do not undo fixes. Store repeatable command output, owner contacts, rollback evidence, normal examples, and post-change verification steps with the operational runbook. Store repeatable command output, owner contacts, rollback evidence, normal examples, and post-change verification steps with the operational runbook.
Common mistakes
Leaving the default rule active so the subscription receives every message despite adding a narrow filter.
Filtering on a property name the publisher never sets or recently renamed.
Using broad SQL expressions that deliver too many messages and hide downstream cost or lag.
Deleting a rule in production without exporting the previous expression for rollback.
Assuming filters provide security instead of also using Service Bus authorization and network controls.