Service Bus Message Filters and Actions

Azure Service Bus Filters and Actions control which messages a subscription receives and how those messages are modified before delivery. Filters act as gatekeepers — they decide whether a message passes into a subscription. Actions act as transformers — they modify message properties after the filter approves the message.

Why Filters and Actions Matter

A topic receives order events from all regions and all order types. Without filters, every subscription receives every message, even irrelevant ones. Filters allow each subscription to select only the messages it needs. This keeps services decoupled and avoids unnecessary processing.

Topic: order-events
  Receives: ALL orders from ALL regions, ALL types

  Without filters: ALL subscriptions get ALL messages
  With filters:    Each subscription gets ONLY its relevant messages

  [india-sub]    receives: Region = 'India'
  [express-sub]  receives: OrderType = 'Express'
  [high-val-sub] receives: Amount > 10000

Types of Filters

1. True Filter (Default)

When a subscription is created without an explicit filter, the default rule uses a True Filter. Every message that enters the topic reaches the subscription.

Subscription: analytics-sub
  Filter: TRUE (default)
  Result: Receives ALL messages published to the topic

2. False Filter

A False Filter blocks all messages. No message reaches the subscription. This temporarily disables a subscription without deleting it.

az servicebus topic subscription rule create \
  --resource-group rg-messaging-prod \
  --namespace-name myshopns \
  --topic-name order-events \
  --subscription-name analytics-sub \
  --name pause-rule \
  --filter-sql-expression "1=0"

3. SQL Filter

A SQL Filter uses a WHERE-clause style expression to evaluate message properties. It supports comparisons, logical operators, and string functions. Only messages where the expression evaluates to TRUE pass through.

SQL Filter Syntax Reference

SQL Filter — System Properties Available

Create a SQL Filter via CLI

# Remove default True filter first
az servicebus topic subscription rule delete \
  --resource-group rg-messaging-prod \
  --namespace-name myshopns \
  --topic-name order-events \
  --subscription-name india-sub \
  --name "$Default"

# Add custom SQL filter
az servicebus topic subscription rule create \
  --resource-group rg-messaging-prod \
  --namespace-name myshopns \
  --topic-name order-events \
  --subscription-name india-sub \
  --name india-high-value-filter \
  --filter-sql-expression "Region = 'India' AND Amount > 1000"

Create a SQL Filter via .NET SDK

using Azure.Messaging.ServiceBus.Administration;

var adminClient = new ServiceBusAdministrationClient(connectionString);

// Delete the default True filter
await adminClient.DeleteRuleAsync("order-events", "india-sub", "$Default");

// Add SQL filter
await adminClient.CreateRuleAsync(
    "order-events",
    "india-sub",
    new CreateRuleOptions
    {
        Name   = "india-high-value-filter",
        Filter = new SqlRuleFilter("Region = 'India' AND Amount > 1000")
    }
);

Console.WriteLine("SQL filter created.");

4. Correlation Filter

A Correlation Filter matches exact values on one or more specific properties. It is faster than SQL filters because Service Bus uses an optimized matching path instead of evaluating a SQL expression.

Use a Correlation Filter when:

• The filter checks only equality (no greater-than, LIKE, or OR logic)
• Performance at scale is important
• Routing is based on Subject, CorrelationId, ContentType, or custom properties

Correlation Filter — .NET

await adminClient.CreateRuleAsync(
    "order-events",
    "express-sub",
    new CreateRuleOptions
    {
        Name   = "express-orders-filter",
        Filter = new CorrelationRuleFilter
        {
            Subject         = "NewOrder",
            ApplicationProperties =
            {
                { "OrderType", "Express" },
                { "Region",    "India"   }
            }
        }
    }
);

// This filter passes ONLY messages where:
//   Subject     = "NewOrder"   AND
//   OrderType   = "Express"    AND
//   Region      = "India"

Filter Actions

A Filter Action modifies message properties after the filter passes the message. The action runs before the message reaches the subscription consumer. This allows enriching or tagging messages per subscription without changing the original message at the topic level.

Action Use Cases

SQL Action Syntax

Create a Filter with an Action — .NET

await adminClient.CreateRuleAsync(
    "order-events",
    "priority-sub",
    new CreateRuleOptions
    {
        Name   = "high-value-priority-filter",
        Filter = new SqlRuleFilter("Amount > 5000"),
        Action = new SqlRuleAction("SET Priority = 'Urgent'; SET NeedsManagerApproval = true")
    }
);

// Messages with Amount > 5000 reach priority-sub
// Properties added before consumer reads the message:
//   Priority              = "Urgent"
//   NeedsManagerApproval  = true

Full Filter and Action Flow Diagram

Publisher sends message:
  { Subject: "NewOrder", Region: "India", Amount: 8000, OrderType: "Express" }

Topic: order-events
  |
  |-- [india-sub] Filter: Region = 'India' AND Amount > 1000
  |       --> PASSES (Region=India, Amount=8000 > 1000)
  |       Action: SET Priority = 'High'
  |       Consumer receives: { ...original..., Priority: "High" }
  |
  |-- [express-sub] Filter: OrderType = 'Express'
  |       --> PASSES (OrderType=Express)
  |       No action
  |       Consumer receives: original message unchanged
  |
  |-- [us-sub] Filter: Region = 'US'
          --> BLOCKED (Region is India, not US)
          Consumer receives: NOTHING

List Existing Rules on a Subscription

az servicebus topic subscription rule list \
  --resource-group rg-messaging-prod \
  --namespace-name myshopns \
  --topic-name order-events \
  --subscription-name india-sub \
  --output table

Summary

Message filters in Azure Service Bus control which messages each topic subscription receives. True and False filters are simple on/off switches. SQL filters evaluate logical expressions against message properties. Correlation filters match exact property values and perform faster at scale. Actions modify message properties after a filter match, enabling per-subscription message enrichment. Together, filters and actions allow precise, efficient routing of messages across multiple consumers without any changes to the publisher code.