Specifying event duration in windows

Apama Documentation : Developing Apama Applications : Developing Apama Applications in EPL : Defining Queries : Defining query input : 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:w1 -> Withdrawal: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_literal

within 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 Escaping keywords to use them as identifiers.

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.

Note:

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 6 min 15 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 a userId 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 a user Id of "Dan" because an event is added to a window in the partition identified by a user Id of "Ray".

Contact Support | Community | Feedback