Apama 10.15.0 | Developing Apama Applications | Developing Apama Applications in EPL | Defining Queries | Finding and acting on event patterns | Defining event patterns | Query conditions
 
Query conditions
A find statement can specify conditions that determine whether there is a match for the specified event pattern. The following table provides an overview of the conditions you can specify.
Condition:
where
within
without
Specifies:
Boolean expression
Time period
Event type coassigned to an identifier
Latest event can cause a match when:
The Boolean expression evaluates to true.
Events in the pattern (or, if specified, the between range) must have been received within the time specified. That is, the elapsed time from when the first event was received to when the last event was received must be less than the within time period.
An event of a specified type was not added to a window after the addition of the oldest event in the potential match set nor before the addition of the latest event.
Number allowed:
Zero or more
Zero or more
Zero or more
Order when all conditions are specified:
1st
2nd
3rd
Format:
where boolean_expression
within time_literal
without typeId as coassignmentID
You can use either as or the colon (:) as the coassignment operator.
Notes:
where x where y
is equivalent to
where x and y
A where clause that precedes any within or without clauses is referred to as a find where clause.
Alternatively, you can specify within expression. The expression must evaluate to a float.
Optionally, after each within clause, you can specify a between clause. See Query condition ranges.
Optionally, after each without clause you can specify one where clause, which is referred to as a without where clause to distinguish it from a find where clause.
Optionally, after each without clause, you can specify a between clause. See Query condition ranges.
Query where clause
A where clause filters which events match. A where clause consists of the where keyword followed by a Boolean expression that refers to the events you are interested in.
Coassignment variables specified in the find statement are in scope in the find where clause. Also available in the find where clause are any parameter values and key values. However, each where clause cannot use or-terms (coassignments that are not required as they are on one side of an or operator in the pattern) from both sides of an or operator in the pattern. Each where clause can only use coassignments from at most one side of every or operator in the pattern. Different where clauses can use coassignments from different sides of an or operator (see Query or operator). Thus, when writing where clauses which apply to either side of an or, use separate where clauses for each condition. They cannot be combined into a single where clause with an or or and operator in the where clause; they may require both sides to be evaluated.
For example, instead of
find OrderPlaced:placed or OrderCancelled:cancelled
where placed.orderId = 1 or cancelled.orderId = 2
write the following:
find OrderPlaced:placed or OrderCancelled:cancelled
where placed.orderId = 1
where cancelled.orderId = 2
For where clauses that do not use any coassignments, all of the Boolean expressions must evaluate to true for the events to match.
For where clauses that use or-terms, they only apply if the events they make use of are matched by the pattern. If they use or-terms that have not been matched by the pattern, then those where clauses are ignored as they cannot be evaluated.
All of the where clauses that can be evaluated must be true for the pattern to match. If a single where clause combines (with an and or or operator) conditions on an or-term and a normal coassignment, then the entire where clause is ignored if the or-term is not matched.
The where clause is optional. You can specify zero, one or more where clauses.
Note: 
You can specify a find where clause that applies to the event pattern and you can also specify a without where clause that is part of a without clause. Any where clauses that you want to apply to the event pattern must precede any within or without clauses.
Query within clause
A within clause sets the time period during which events in the match set must have been added to their windows. A pattern can specify zero, one, or more within clauses. These must appear after any find where clauses and before any without clauses. The format of a within clause is as follows. The between clause is optional.
within durationExpression [ between ( identifer1 identifier2 ... ) ]
The durationExpression must be a time literal (such as 2 min 3 seconds) or it must evaluate to a float value. A float expression can use constants and parameters. It indicates a number of seconds.
For example, consider the following find statement:
find LoggedIn as lc -> OneTimePass as otp
where lc.user = otp.user
within 30.0 {
emit AccessGranted(lc.user);
}
If specified, the between clause lists two or more items. Each item can be a coassigned event in the pattern. A wait coassignment can also be specified. These items define a range. See Query condition ranges. For example:
find wait(1.) as w -> A as a {
...
within (5.0) between w a
Now assume that the following events arrive:
Time
Event
Access Granted?
10
LoggedIn("Andy")
15
OneTimePass("Andy")
Yes. Both events received within 30 seconds.
20
LoggedIn("Mike")
60
OneTimePass("Mike")
No. OneTimePass event received more than 30 seconds after corresponding LoggedIn event.
60
LoggedIn("Sam")
90
OneTimePass("Sam")
No. OneTimePass event received exactly 30 seconds after corresponding LoggedIn event. For there to be a match, the OneTimePass event must be received less than 30 seconds after its corresponding LoggedIn event.
As mentioned earlier, a find statement can specify multiple within clauses. This is useful when the pattern of interest refers to multiple events and you specify a between range as part of each within clause. When you specify multiple within clauses they must all be satisfied for there to be a match.
Query without clause
A without clause specifies event types, which must be specified in the inputs block of the query, whose presence prevents a match. For example, if a potential match set contains 3 events, it can be a match only if a type specified in a without clause was not added to a window neither after the first event nor before the third event. Any event type that can be used in the find pattern can be used in the without clause.
Optionally, after each without clause, you can specify one where clause, which is referred to as a without where clause to distinguish it from a find where clause. The following table compares find where clauses and without where clauses.
Find where clause
Without where clause
true allows a match. Think of this as a positive where clause.
false allows a match. Think of this as a negative where clause.
Can only be before any within or without clauses
Can only be part of a without clause
Applies to the event pattern
Applies to the event specified in its without clause
Cannot refer to event specified in without clause
Can refer to event specified in without clause
The absence of an event of a type specified in a without clause has the same effect as the presence of an event for which the without where clause evaluates to false.
In addition to being able to refer to parameters and coassignment identifiers in the event pattern, a without where clause can refer to the one event mentioned in its without clause. When a without where clause evaluates to true, the presence of the without event prevents a match. If a without where clause is false, then that without event instance is ignored; that is, a match is possible.
A without clause cannot use the -> or and pattern operators. However, you can specify multiple without clauses. If there are multiple without clauses each one can refer to only its own coassignment and not coassignments in other without clauses. However, all without clauses can make use of the pattern's standard coassignments, such as od.user in the example at the end of this topic.
If there are multiple without clauses a matching event for any one of them prevents a pattern match. Multiple without clauses can use the same type and the same coassignment, which is useful only when their where conditions are different.
Typically, a without where clause references the event in its without clause, but this is not a requirement.
Optionally, after each without clause, you can specify a between clause, which lists two or more coassigned events. It can also list a wait coassignment. For an event to cause a match, the type specified in the without clause cannot be added to the window between the points specified in the between clause. See Query condition ranges.
Any without clauses must be after any find where clauses and within clauses. If you specify both optional clauses, the without where clause must be before the between clause.
When a without clause includes both optional clauses, where and between, the format looks like this:
without typeId as coassignmentId
where boolean_expression
between ( identifier1 identifier2... )
As mentioned previously, a find where clause applies to the event pattern while a without where clause applies to the event specified in its without clause. The following table shows the resulting behavior according to the type of the where clause and the value of its Boolean expression:
Type of where clause
Boolean expression evaluates to true
Boolean expression evaluates to false
Find where clause applies to event pattern
Allows match
Prevents match
Without where clause applies to its without event
Prevents match
Allows match
Example
Consider the following find statement:
find OuterDoorOpened as od -> InnerDoorOpened as id
where od.user = id.user
without SecurityCodeEntered as sce where od.user = sce.user {
emit Alert("Intruder "+id.user);
}
Now suppose the following events arrive:
Event Received
Result
OuterDoorOpened("Andrew")
SecurityCodeEntered("Andrew")
Causes the without where clause to evaluate to true, which prevents a match.
InnerDoorOpened("Andrew")
No alert is set.
OuterDoorOpened("Brian")
InnerDoorOpened("Brian")
Because there is no intermediate SecurityCodeEntered event, there is a match and the query sends an alert. This is an example of how the absence of an event of a type specified in a without clause has the same effect as the presence of an event for which the without where clause evaluates to false.
OuterDoorOpened("Chris")
SecurityCodeEntered("Charlie")
Causes the without where clause to evaluate to false, which allows a match.
InnerDoorOpened("Chris")
Causes a match and the query sends an alert.
OuterDoorOpened("Dan")
SecurityCodeEntered("David")
Causes the without where clause to evaluate to false, which allows a match.
SecurityCodeEntered("Dan")
Causes the without where clause to evaluate to true, which prevents a match.
SecurityCodeEntered("Densel")
Causes the without where clause to evaluate to false, which allows a match.
InnerDoorOpened("Dan")
There is no match because one of the SecurityCodeEntered events caused the without where clause to evaluate to true, which prevents a match.