Apama 10.15.0 | Developing Apama Applications | EPL Reference | Expressions | Stream queries | Stream query window definitions
 
Stream query window definitions
In a stream query, the optional window definition specifies which items in a stream to operate on. See also Adding window definitions to from and join clauses.
Syntax diagram for stream query window definition
Typically, stream queries process a window over a stream. A stream is an ordered sequence of items over time. A window specifies which items to operate on. Windows can contain a portion of the stream based on number of items, time of item arrival, content of item, or other criteria.
When the stream query window definition is retain all, the window contains all items that have ever been in the stream. Conceptually, once an item enters a retain all window, it remains in the window indefinitely, or until the stream query is terminated. The retain all clause specifies an unbounded window. Unbounded windows have restrictions on their use:
*You cannot have a partitioned or batched unbounded window.
*You cannot perform a join operation on an unbounded window.
*You cannot specify an unbounded window when you use rstream in the select clause of a stream query.
When you use a custom aggregate function in a stream query that contains an unbounded window, you cannot use a bounded aggregate function. You should also be aware that, if you use a badly implemented custom aggregate function in a stream query that contains an unbounded window, then this can result in uncontrolled memory usage.
A partition by clause divides the input data into several partitions and then applies the stream query window definition separately to each partition. The partition by expressions must be comparable types.
The retain clause specifies the maximum number of items to be retained by the window. The retain expression must be an integer expression. In a size-based window, as each new item arrives in the stream, it is added to the window. After the number of items in the window reaches the window size limit specified in the retain clause, the arrival of a new item causes removal of the oldest item from the window.
The within clause specifies the number of seconds to keep each new item in the window. The within expression must be a float expression. In a time-based window, as each new item arrives in the stream, it is added to the window. As soon as an item has been in the window for the number of seconds specified by the within expression, the correlator removes the item from the window.
By default, the contents of a window change upon the arrival of each item. The every keyword can be used to control when the contents of the window change, which causes the items to be added to the window in batches of several items at once. Time-based windows can be controlled to update only every p seconds and size-based windows can be controlled to update only every m events.
The contents of the window can also depend on the content of individual items in the stream. Specify with unique Expression to limit the window to containing only the most recent item for each key value identified by the expression.
Semantic constraints
In a stream query window definition for one of a joined stream query's input streams, it is always an error to refer to the other input stream's item identifier.
partition by Expression, Expression, ...
You should use the item identifier in each expression. Expressions can return any comparable types.
retain Expression [every Expression]
You cannot use the item identifier in these expressions. These expressions must return integer values.
within Expression [every Expression]
You cannot use the item identifier in these expressions. These expressions must return float values.
with unique Expression
You should use the item identifier in this expression. The expression can return any comparable type.