Comparison operators for use in event patterns in Amazon EventBridge
Below a summary of all the comparison operators available in EventBridge.
Comparison operators only work on leaf nodes, with the exception of $or
and anything-but
.
Comparison | Example | Rule syntax | Event bus support | Pipe support |
---|---|---|---|---|
And |
Location is "New York" and Day is "Monday" |
|
Yes |
Yes |
Anything-but | State is any value besides "initializing". |
|
Yes |
Yes |
Anything-but (begins with) | Region is not in the US. |
|
Yes |
No |
Anything-but (ends with) | FileName does not end with a .png extension. |
|
Yes |
No |
Anything-but (ignore case) | State is any value besides "initializing" or any other casing variation, such as "INITIALIZING". |
|
Yes |
No |
Anything-but using a wildcard | FileName is not a file path that includes |
|
Yes |
No |
Region is in the US. |
|
Yes |
Yes |
|
Begins with (ignore case) | Service name starts with the letters "eventb", regardless of case. |
|
Yes |
Yes |
LastName is empty. |
|
Yes |
Yes |
|
Equals |
Name is "Alice" |
|
Yes |
Yes |
Name is "Alice" |
|
Yes |
Yes |
|
FileName ends with a .png extension |
|
Yes |
Yes |
|
Ends with (ignore case) | Service name ends with the letters "tbridge", or any other casing variation, such as "TBRIDGE". |
|
Yes |
Yes |
ProductName exists |
|
Yes |
Yes |
|
ProductName does not exist |
|
Yes |
Yes |
|
Weather is anything but "Raining" |
|
Yes |
Yes |
|
UserID is null |
|
Yes |
Yes |
|
Price is 100 |
|
Yes |
Yes |
|
Price is more than 10, and less than or equal to 20 |
|
Yes |
Yes |
|
Or |
PaymentType is "Credit" or "Debit" |
|
Yes |
Yes |
Location is "New York", or Day is "Monday". |
|
Yes |
Yes |
|
Any file with a .png extension, located within the folder "dir" |
|
Yes |
No |
Prefix matching
You can match an event depending on the prefix of a value in the event source. You can use prefix matching for string values.
For example, the following event pattern would match any event where the
"time"
field started with "2017-10-02"
such as
"time": "2017-10-02T18:43:48Z"
.
{
"time": [ { "prefix": "2017-10-02" } ]
}
Prefix matching while ignoring case
You can also match a prefix value regardless of the casing of the characters a
value begins with, using equals-ignore-case
in conjunction with
prefix.
For example, the following event pattern would match any event where the
service
field started with the character string
EventB
, but also EVENTB
, eventb
, or any other
capitalization of those characters.
{
"detail": {"service" : [{ "prefix": { "equals-ignore-case": "EventB" }}]}
}
Suffix matching
You can match an event depending on the suffix of a value in the event source. You can use suffix matching for string values.
For example, the following event pattern would match any event where the
"FileName"
field ends with the .png
file extension.
{
"FileName": [ { "suffix": ".png" } ]
}
Suffix matching while ignoring case
You can also match a suffix value regardless of the casing of the characters a
value ends with, using equals-ignore-case
in conjunction with
suffix.
For example, the following event pattern would match any event where the
FileName
field ended with the character string .png
,
but also .PNG
or any other capitalization of those characters.
{
"detail": {"FileName" : [{ "suffix": { "equals-ignore-case": ".png" }}]}
}
Anything-but matching
Anything-but matching matches anything except what's specified in the rule.
You can use anything-but matching with strings and numeric values, including lists that contain only strings, or only numbers.
The following event pattern shows anything-but matching with strings and numbers.
{
"detail": {
"state": [ { "anything-but": "initializing" } ]
}
}
{
"detail": {
"x-limit": [ { "anything-but": 123 } ]
}
}
The following event pattern shows anything-but matching with a list of strings.
{
"detail": {
"state": [ { "anything-but": [ "stopped", "overloaded" ] } ]
}
}
The following event pattern shows anything-but matching with a list of numbers.
{
"detail": {
"x-limit": [ { "anything-but": [ 100, 200, 300 ] } ]
}
}
Anything-but matching while ignoring case
You can also use equals-ignore-case
in conjunction with
anything-but
, to match string values regardless of character
casing.
The following event pattern matches state
fields that do not contain
the string "initializing", "INITIALIZING", "Initializing", or any other
capitalization of those characters.
{
"detail": {"state" : [{ "anything-but": { "equals-ignore-case": "initializing" }}]}
}
You can use equals-ignore-case
in conjunction with
anything-but
to match against a list of values as well:
{
"detail": {"state" : [{ "anything-but": { "equals-ignore-case": ["initializing", "stopped"] }}]}
}
Anything-but matching on prefixes
You can use prefix
in conjunction with anything-but
to match string values that do not start with the specified value.
This includes single values, or a list of values.
The following event pattern shows anything-but matching that matches any event
that does not have the prefix "init"
in the "state"
field.
{
"detail": {
"state": [ { "anything-but": { "prefix": "init" } } ]
}
}
The following event pattern shows anything-but matching used with a list of prefix
values. This event pattern matches any event that does not have either the prefix
"init"
or "stop"
in the "state"
field.
{
"detail": {
"state" : [{ "anything-but": { "prefix": ["init", "stop"] } } ] }
}
}
Anything-but matching on suffixes
You can use suffix
in conjunction with anything-but
to
match string values that do not end with the specified value.
This includes single values, or a list of values.
The following event pattern matches any values for the FileName
field
that do not end with .txt
.
{
"detail": {
"FileName": [ { "anything-but": { "suffix": ".txt" } } ]
}
}
The following event pattern shows anything-but matching used with a list of suffix
values. This event pattern matches any values for the FileName
field
that do not end with either .txt
or .rtf
.
{
"detail": {
"FileName": [ { "anything-but": { "suffix": [".txt", ".rtf"] } } ]
}
}
Anything-but matching using wildcards
You can use the wildcard character (*) within the values you specify for anything-but matching. This includes single values, or a list of values.
The following event pattern matches any values for the FileName
field
that do not contain /lib/
.
{
"detail": {
"FilePath" : [{ "anything-but": { "wildcard": "*/lib/*" }}]
}
}
The following event pattern shows anything-but matching used with a list of values
including wildcards. This event pattern matches any values for the
FileName
field that do not contain either /lib/
or
/bin/
.
{
"detail": {
"FilePath" : [{ "anything-but": { "wildcard": ["*/lib/*", "*/bin/*"] }}]
}
}
For more information, see Matching using wildcards.
Numeric matching
Numeric matching works with values that are JSON numbers. It is limited to values between -5.0e9 and +5.0e9 inclusive, with 15 digits of precision, or six digits to the right of the decimal point.
The following shows numeric matching for an event pattern that only matches events that are true for all fields.
{
"detail": {
"c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ],
"d-count": [ { "numeric": [ "<", 10 ] } ],
"x-limit": [ { "numeric": [ "=", 3.018e2 ] } ]
}
}
IP address matching
You can use IP address matching for IPv4 and IPv6 addresses. The following event pattern shows IP address matching to IP addresses that start with 10.0.0 and end with a number between 0 and 255.
{
"detail": {
"sourceIPAddress": [ { "cidr": "10.0.0.0/24" } ]
}
}
Exists matching
Exists matching works on the presence or absence of a field in the JSON of the event.
Exists matching only works on leaf nodes. It does not work on intermediate nodes.
The following event pattern matches any event that has a detail.state
field.
{
"detail": {
"state": [ { "exists": true } ]
}
}
The preceding event pattern matches the following event.
{
"version": "0",
"id": "7bf73129-1428-4cd3-a780-95db273d1602",
"detail-type": "EC2 Instance State-change Notification",
"source": "aws.ec2",
"account": "123456789012",
"time": "2015-11-11T21:29:54Z",
"region": "us-east-1",
"resources": ["arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"],
"detail": {
"instance-id": "i-abcd1111",
"state": "pending"
}
}
The preceding event pattern does NOT match the following event because it doesn't have
a detail.state
field.
{
"detail-type": [ "EC2 Instance State-change Notification" ],
"resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-02ebd4584a2ebd341" ],
"detail": {
"c-count" : {
"c1" : 100
}
}
}
Equals-ignore-case matching
Equals-ignore-case matching works on string values regardless of case.
The following event pattern matches any event that has a detail-type
field that matches the specified string, regardless of case.
{
"detail-type": [ { "equals-ignore-case": "ec2 instance state-change notification" } ]
}
The preceding event pattern matches the following event.
{
"detail-type": [ "EC2 Instance State-change Notification" ],
"resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-02ebd4584a2ebd341" ],
"detail": {
"c-count" : {
"c1" : 100
}
}
}
Matching using wildcards
You can use the wildcard character (*) to match string values in event patterns.
Note
Currently the wildcard character is supported in event bus rules only.
Considerations when using wildcards in your event patterns:
-
You can specify any number of wildcard characters in a given string value; however, consecutive wildcard characters are not supported.
-
EventBridge supports using the backslash character (\) to specify the literal * and \ characters in wildcard filters:
-
The string
\*
represents the literal * character -
The string
\\
represents the literal \ character
Using the backslash to escape other characters is not supported.
-
Wildcards and event pattern complexity
There is a limit to how complex a rule using wildcards can be. If a rule is too
complex, EventBridge returns an InvalidEventPatternException
when attempting
to create the rule. If your rule generates such an error, consider using the
guidance below to reduce the complexity of the event pattern:
-
Reduce the number of wildcard characters used
Only use wildcard characters where you truly need to match against multiple possible values. For example, consider the following event pattern, where you want to match against event buses in the same Region:
{ "EventBusArn": [ { "wildcard": "*:*:*:*:*:event-bus/*" } ] }
In the above case, many of the sections of the ARN will be directly based on the Region in which your event buses reside. So if you are using the
us-east-1
Region, a less complex pattern that still matches the desired values might be the following example:{ "EventBusArn": [ { "wildcard": "arn:aws:events:us-east-1:*:event-bus/*" } ] }
-
Reduce repeating character sequences that occur after a wildcard character
Having the same character sequence appear multiple times after the use of a wildcard increases the complexity of processing the event pattern. Recast your event pattern to minimize repeated sequences. For example, consider the following example, that matches on the file name
doc.txt
file for any user:{ "FileName": [ { "wildcard": "/Users/*/dir/dir/dir/dir/dir/doc.txt" } ] }
If you knew that the
doc.txt
file would only occur in the specified path, you could reduce the repeated character sequence in this way:{ "FileName": [ { "wildcard": "/Users/*/doc.txt" } ] }
Complex example with multiple matching
You can combine multiple matching criteria into a more complex event pattern. For
example, the following event pattern combines anything-but
and
numeric
.
{
"time": [ { "prefix": "2017-10-02" } ],
"detail": {
"state": [ { "anything-but": "initializing" } ],
"c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ],
"d-count": [ { "numeric": [ "<", 10 ] } ],
"x-limit": [ { "anything-but": [ 100, 200, 300 ] } ]
}
}
Note
When building event patterns, if you include a key more than once the last reference will be the one used to evaluate events. For example, for the following pattern:
{ "detail": { "location": [ { "prefix": "us-" } ], "location": [ { "anything-but": "us-east" } ] } }
only { "anything-but": "us-east" }
will be taken into account when
evaluating the location
.
Complex example with $or
matching
You can also create complex event patterns that check to see if
any field values match, across multiple fields. Use
$or
to create an event pattern that matches if any of the values for
multiple fields are matched.
Note that you can include other filter types, such as numeric matching and arrays, in your pattern matching for
individual fields in your $or
construct.
The following event pattern matches if any of the following conditions are met:
-
The
c-count
field is greater than 0 or less than or equal to 5. -
The
d-count
field is less than 10. -
The
x-limit
field equals 3.018e2.
{
"detail": {
"$or": [
{ "c-count": [ { "numeric": [ ">", 0, "<=", 5 ] } ] },
{ "d-count": [ { "numeric": [ "<", 10 ] } ] },
{ "x-limit": [ { "numeric": [ "=", 3.018e2 ] } ] }
]
}
}
Note
APIs that accept an event pattern (such as PutRule
,
CreateArchive
, UpdateArchive
, and
TestEventPattern
) will throw an
InvalidEventPatternException
if the use of $or
results
in over 1000 rule combinations.
To determine the number of rule combinations in an event pattern, multiply the
total number of arguments from each $or
array in the event pattern. For
example, the above pattern contains a single $or
array with three
arguments, so the total number of rule combinations is also three. If you added
another $or
array with two arguments, the total rule combinations would
then be six.