Window definition syntax
There are a number of different formats and keywords that you can use to define a window on a stream. Following are the alternatives you can choose from. See the subsequent topics for details.
[partition by partitionByExpr[, partitionByExpr]...]
(
within windowDurationExpr[every batchPeriodExpr]
[retain windowSizeExpr] [with unique keyExpr]
| retain windowSizeExpr [every batchSizeExpr] [with unique keyExpr]
)
| retain all
Every window definition specifies retain, within or both.
Syntax description
partitionByExpr | Optionally specifies an EPL expression that should involve the input item in some way and that returns a comparable type. A partition by clause effectively creates a separate window for each encountered distinct value of partitionByExpr. |
windowDurationExpr | Specifies a float expression that indicates a duration of a number of seconds. The window contains the items received within the last windowDurationExpr seconds. See Defining time-based windows. |
batchPeriodExpr | Specifies a float expression that indicates an interval period of a number of seconds. The window updates its contents every batchPeriodExpr seconds. See Defining batched windows. |
windowSizeExpr | Specifies an integer expression that indicates the number of items you want to retain in the window. The window contains the most recent windowSizeExpr items. See Defining size-based windows. |
keyExpr | Specifies an EPL expression that must contain at least one reference to the input item and must return a comparable type. See Comparable types. If you add a with unique clause, if there is more than one item in the window that has the same value for the key identified by keyExpr, only the most recently received item is considered to be in the window. See Defining content-dependent windows. |
batchSizeExpr | Specifies an integer expression that indicates a number of items. The window updates its contents after every batchSizeExpr items that match the query are found. See Defining batched windows. |
Omitting the window definition
The window definition is optional in a stream query. If you do not specify any window then, for any given activation of the stream query, the stream query operates on only the items that are current for that activation. Typically this is a single event. However, if the source for this query is, for example, a stream query with a batched window then the items in each batch will be processed together as in the following example:
stream<A> sA := from a in all A() retain 4 every 4 select a;
from a in sA select count(): c { ... }
The second query receives batches of four
A events and will generate a single aggregate value for each batch. For more details see
Stream queries that generate lots.
Retaining all items
The simplest window is one that contains all items that have ever been in the stream. The corresponding window definition is retain all. Conceptually, once an item enters a retain all window, it remains in the window indefinitely (or until the stream query is terminated). The following query evaluates the running mean of all items that have ever been in the values stream:
stream <decimal> means := from v in values retain all select mean(v);
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 query.
When you use a custom (user-defined) aggregate function in a query that contains an unbounded window, you cannot also use a bounded aggregate function. You should also be aware that, if you use a badly implemented custom aggregate function in a query that contains an unbounded window, then this can result in uncontrolled memory usage. See
Defining custom aggregate functions.