Filtering

Event filtering is configurable on each subscriber using the filter model defined in the Azure Event Grid documentation.

Basic Filtering

Event Type Filtering

Filter events by their event type:

{
  "filter": {
    "includedEventTypes": ["my.eventType"]
  }
}

Subject Filtering

Filter events by their subject:

{
  "filter": {
    "subjectBeginsWith": "/blobServices/default/containers/mycontainer/log",
    "subjectEndsWith": ".jpg",
    "isSubjectCaseSensitive": true
  }
}

Advanced Filtering

Advanced filters provide more complex filtering capabilities:

{
  "filter": {
    "advancedFilters": [
      {
        "operatorType": "NumberGreaterThanOrEquals",
        "key": "Data.Key1",
        "value": 5
      },
      {
        "operatorType": "StringContains",
        "key": "Subject",
        "values": ["container1", "container2"]
      }
    ]
  }
}

Filtering on Arrays

When the event property being filtered is an array, you can enable array filtering to match against individual array elements. This feature was introduced in Azure Event Grid API version 2020-10-15-preview.

Enabling Array Filtering

Set enableAdvancedFilteringOnArrays to true in your filter configuration:

{
  "filter": {
    "enableAdvancedFilteringOnArrays": true,
    "advancedFilters": [
      {
        "operatorType": "StringContains",
        "key": "Data.Tags",
        "values": ["important"]
      }
    ]
  }
}

How Array Filtering Works

When enableAdvancedFilteringOnArrays is enabled and the event property is an array:

• Positive operators (StringIn, StringContains, NumberIn, etc.): The filter matches if any array element satisfies the condition
• Negation operators (StringNotIn, StringNotContains, NumberNotIn, etc.): The filter matches only if all array elements satisfy the condition

Example

Given an event with array data:

{
  "data": {
    "tags": ["urgent", "customer", "billing"]
  }
}

Filter	enableAdvancedFilteringOnArrays	Result
StringContains with ["urgent"]	true	Match - "urgent" is in the array
StringContains with ["urgent"]	false	No match - array is not a string
StringNotContains with ["test"]	true	Match - no element contains "test"
StringNotContains with ["urgent"]	true	No match - "urgent" is in the array

Complete Example

{
  "topics": [
    {
      "name": "OrdersTopic",
      "port": 60101,
      "key": "TheLocal+DevelopmentKey=",
      "subscribers": [
        {
          "name": "HighPriorityOrders",
          "endpoint": "http://localhost:7071/api/ProcessHighPriority",
          "filter": {
            "enableAdvancedFilteringOnArrays": true,
            "advancedFilters": [
              {
                "operatorType": "StringIn",
                "key": "Data.Categories",
                "values": ["premium", "vip"]
              }
            ]
          }
        }
      ]
    }
  ]
}

This subscriber receives events where the Data.Categories array contains either "premium" or "vip".

Advanced Filter Operators

Each advanced filter requires an operatorType, a key (the event property to filter on), and either a value, values, or no value property depending on the operator type.

Limit: Up to 25 advanced filters can be configured per subscription.

Number Operators

Operator	Property	Description
NumberGreaterThan	value	Event value must be greater than the specified number
NumberGreaterThanOrEquals	value	Event value must be greater than or equal to the specified number
NumberLessThan	value	Event value must be less than the specified number
NumberLessThanOrEquals	value	Event value must be less than or equal to the specified number
NumberIn	values	Event value must match one of the specified numbers (max 5 values)
NumberNotIn	values	Event value must not match any of the specified numbers (max 5 values)
NumberInRange	values	Event value must be within one of the specified ranges (e.g., [[0, 10], [20, 30]])
NumberNotInRange	values	Event value must not be within any of the specified ranges

String Operators

Operator	Property	Description
StringContains	values	Event value must contain at least one of the specified strings
StringNotContains	values	Event value must not contain any of the specified strings
StringBeginsWith	values	Event value must begin with at least one of the specified strings
StringNotBeginsWith	values	Event value must not begin with any of the specified strings
StringEndsWith	values	Event value must end with at least one of the specified strings
StringNotEndsWith	values	Event value must not end with any of the specified strings
StringIn	values	Event value must match one of the specified strings (max 5 values)
StringNotIn	values	Event value must not match any of the specified strings (max 5 values)

Boolean and Null Operators

Operator	Property	Description
BoolEquals	value	Event value must equal the specified boolean
IsNullOrUndefined	(none)	Key must be null or not exist
IsNotNull	(none)	Key must exist and have a non-null value

Key Path Syntax

The key property supports nested data properties using dot notation:

• Top-level fields: Subject, EventType, Id, etc.
• Data properties: Data.MyProperty or Data.Nested.Value

Important Notes

• String comparisons in advanced filters are case-insensitive
• "Not" operators (StringNotIn, NumberNotIn, etc.) return true when the key doesn't exist

Value Limits

Advanced filters have the following limits:

Limit	Value
Maximum advanced filters per subscription	25
Maximum string length per value	512 characters
Maximum values for In/NotIn operators	5 values
Maximum range pairs for InRange/NotInRange	5 ranges

Complete Example

{
  "topics": [
    {
      "name": "MyAwesomeTopic",
      "port": 60101,
      "key": "TheLocal+DevelopmentKey=",
      "subscribers": [
        {
          "name": "LocalAzureFunctionSubscription",
          "endpoint": "http://localhost:7071/runtime/webhooks/EventGrid?functionName=PersistEventToDb",
          "filter": {
            "includedEventTypes": ["my.eventType"],
            "subjectBeginsWith": "/orders/",
            "advancedFilters": [
              {
                "operatorType": "NumberGreaterThanOrEquals",
                "key": "Data.Amount",
                "value": 100
              }
            ]
          }
        }
      ]
    }
  ]
}

Related Topics

• HTTP Subscribers - Configure filters on HTTP subscribers
• Event Hub Subscribers - Configure filters on Event Hub subscribers
• Configuration - Complete configuration reference