Specifying event duration in windows
In an input definition, you can specify an optional within clause that indicates the length of time that an event remains in the window. For example:
query FraudulentWithdrawalDetection {
inputs {
Withdrawal() key userId within 1 hour;
}
find Withdrawal as w1 -> Withdrawal as w2
where w1.city != w2.city {
log "Suspicious withdrawal: " + w2.toString() at INFO;
}
...
}
In this example, a Withdrawal event remains in the window for 1 hour. After 1 hour in the window, an event is ejected. Each time an event is added to one of the windows in a partition, the correlator evaluates the find pattern for that partition. Ejection of an event from a window does not trigger pattern evaluation. There are two formats for specifying a within clause:
within time_literalwithin float_expression Parentheses in within clauses are allowed. The rules for specifying a time literal are:
Specify one or more
integer or
float literal(s) and follow each one with a keyword that indicates a time unit.
Time unit keywords are:
day,
days hour,
hours min,
minute,
minutes sec,
second,
seconds msec,
millisecond,
milliseconds Outside a query, you can use these keywords as identifiers. Inside a query, you cannot use these keywords as identifiers unless you prefix them with a hash symbol (
#). See also
Keywords.
A space is required between an
integer or
float literal and its time unit. A space is required after a time unit if it is followed by an
integer or
float literal. Additional whitespace is allowed.
If you specify more than one time unit keyword they must be in the order of decreasing size. For example,
days must be before
minutes.
You need not specify all time units.
Each time unit keyword must represent a different time unit, that is, you cannot, for example, specify both
day and
days.
Examples of valid time literals:
10 hours 1 days 12 hours 1 day 2 hours 30 minutes 4 sec 2 days 5 minutes 2.5 sec 10 seconds - This is equivalent to specifying the
float expression
10.0.
While it is possible to define time literals using float values, for example, 3.5 days 12.5 hours 33.3 min, it is recommended that you use only integer values when the specification includes more than one time unit. For example, rather than specifying 2 days 65.75 minutes, you should specify 2 days 1 hour 5 min 45 sec.
If you open and edit a query in Apama's Query Designer in Software AG Designer, it modifies the time literal (if necessary) such that it contains only integers. Also, the allowable range of integers is 0 to 23 for hours, 0 to 59 for minutes, 0 to 59 for seconds, and 0 to 999 for milliseconds. Where necessary, the Query Designer rounds up to a whole number of milliseconds. For example, suppose you specify the following time literal in EPL code:
3.5 days 4 hours 27.5 minutes 1002.75 milliseconds
The Query Designer converts this to 3 days 16 hours 27 minutes 31 seconds 3 milliseconds. The actual Query Designer display is: 3d 16h 27m 31s 3ms.
When you specify a float expression it indicates a number of seconds.
Consider the example at the beginning of this topic as the following events are added to their appropriate windows:
Time | Event Added to Window |
10:00 | Withdrawal("Dan", "London") |
10:30 | Withdrawal("Dan", "Dublin") |
10:45 | Withdrawal("Dan", "Paris") |
11:15 | Withdrawal("Ray", "Honolulu") |
11:30 | Withdrawal("Dan", "Rome") |
For the partition identified by user ID Dan, the query evaluates the pattern at the following times:
Time | Window Contents | Matching Events |
10:00 | Withdrawal("Dan", "London") | |
10:30 | Withdrawal("Dan", "Dublin") Withdrawal("Dan", "London") | w1=Withdrawal("Dan", "London") w2=Withdrawal("Dan", "Dublin") |
10:45 | Withdrawal("Dan", "Paris") Withdrawal("Dan", "Dublin") Withdrawal("Dan", "London") | w1=Withdrawal("Dan", "Dublin") w2=Withdrawal("Dan", "Paris") |
11:30 | Withdrawal("Dan", "Rome") Withdrawal("Dan", "Paris") | w1=Withdrawal("Dan", "Paris") w2=Withdrawal("Dan", "Rome") |
An event remains in its window for exactly the specified duration. For example, at 11:00, Withdrawal("Dan", "London") is no longer in the window and at 11:30, Withdrawal("Dan", "Dublin") is no longer in the window. Although the contents of the window have changed, ejection of an event does not cause evaluation of the event pattern.
At 11:15, there is no evaluation of the event pattern for the partition identified by user ID Dan because an event is added to a window in the partition identified by user ID Ray.