Salesforce Event Filter Expressions: Patterns, Examples, and Limitations
Salesforce custom-channel filters look familiar to anyone who writes SOQL, but they should not be treated as unrestricted SOQL WHERE clauses.
Where the Expression Lives
The filter is configured on a PlatformEventChannelMember through its filterExpression. Salesforce evaluates it before delivering matching events on that custom channel.
For CDC, a filter can use record field values and change-operation information. Salesforce's documented example filters Account changes to update operations for selected industries.
Think in Business Events
A good filter answers a stable question such as:
Which changes constitute an event this consumer actually owns?
Examples include:
- updates for customers in selected segments;
- changes associated with a geographic scope;
- only selected change operation types;
- platform events whose fields meet a routing condition.
Avoid encoding rapidly changing application logic into a channel merely because filtering is available.
SOQL-Like, Not Full SOQL
Salesforce states that filter expressions are based on SOQL and support a subset of operators and field types, with limitations.
That distinction matters. Before adopting an expression, validate the exact field type and operator combination against the current Event Filtering documentation and in the target org/API version.
AND/OR Logic
Complex filters can become hard to reason about quickly. Even when an expression is supported, use parentheses deliberately and keep the business rule readable.
Conceptually:
(change type is UPDATE)
AND
(Industry is Banking OR Agriculture)
When the rule becomes a page of boolean logic, consider whether the channel is trying to become a business-rules engine.
Filter Fields Are Included in CDC Events
For CDC custom channels, Salesforce documents that fields used by a filter expression are automatically included in delivered change events. This is useful because a subscriber may need to know why the event matched.
Therefore, if Industry is already part of the filter, don't add it to enrichedFields solely to ensure it is delivered.
Test Boundary Cases
For every production filter, test:
- a record that should match;
- a record that should not match;
- create/update/delete behavior relevant to the rule;
- null values;
- transitions into the matching state;
- transitions out of the matching state;
- fields that are unchanged during an update.
Event filters are routing contracts. A missed edge case can become a missed integration event.
Filtering vs Authorization
Do not use an event filter as a substitute for security architecture. Filtering determines what a channel delivers according to its configuration; authentication, authorization, Salesforce permissions, and downstream data handling remain separate concerns.