Setting the time horizon for global aggregates

A global event aggregate is calculated every time that a referenced event occurs. Global event aggregates run continuously as part of your deployed solution. To control how events associated with global aggregates are stored in memory, you can set event time horizon properties for all aggregates or for a specific aggregate.

About this task

The eventAggregateMaxHorizon property defines a horizon for each event that determines how long the event is retained. The event is stored in working memory during a time window that begins when the event is time stamped, and has a duration as defined by the event time horizon. If you specify an event time horizon property without a specific global aggregate name, then the horizon applies to all aggregates in the solution. For more information, see Server administration properties.

This property applies only to aggregates that implicitly reference now in the where clause, such as during the last period of <time>.

You can set the event time horizon for a specific global aggregate by adding the aggregate name to the property. By default, global aggregate events are retained in memory for one day. A minimum horizon is not supported for aggregates.

Events that are older than the defined event time horizon are removed from the system memory when the engines that are used by an aggregate receive new events after the time horizon passes. However, because many rule engines can be used by a global aggregate, it cannot be assumed that all events are removed from an aggregate at the end of the maximum horizon. When events are removed, this change modifies the value of global aggregates that are computed from the events.

Important: To prevent miscalculation of the event aggregate value, make sure that the time window specified in your event aggregate is less than the eventAggregateMaxHorizon value. If the event aggregate time window is greater than the eventAggregateMaxHorizon value, you must define an aggregate-specific eventAggregateMaxHorizon property and set the value slightly larger than the time window specified in the aggregate definition. Setting this property value ensures that the global aggregate is computed correctly.

A global event aggregate defines a variable that stores the aggregated result of a set of event queries. The variable is represented by a name that begins with defvar, for example: defvarTotalSessionRatings, where TotalSessionRatings is the aggregate of all the session ratings events. To set the event time horizon for a specific global aggregate, include the aggregate name in the eventAggregateMaxHorizon property. Global aggregate variable names are saved in the aggregates folder within the BOM project that is referenced by the solution, in the globalQueries.var file. For example: /MyCreditCardSolutionBOM/aggregates/globalQueries.var.

Procedure

Open the solution_properties.xml file that is in the root folder of the solution project and add the eventAggregateMaxHorizon property to the file.

Example

<property name="eventAggregateMaxHorizon>P2D</property>

Where the global aggregate horizon is two days. The property value indicates how long events that are related to global aggregates remain in memory. In this example, an event that is older than two days is removed.

The eventAggregateMaxHorizon property overrides the time frame that is defined in an aggregate definition. For example, if an aggregate definition .agg file includes the following statement:

define 'the total number of test events' as the number of test events during the last period of 24 hours.

but the maximum horizon is set to PT12H or 12 hours, then the server stores the aggregate events that are created in the past 12 hours instead of 24 hours. In this situation, the computed value of the global aggregate does not match the evaluation criteria in the definition.

To add an event time horizon property for a specific global aggregate, thereby overriding the value that is set for other events, include the aggregate name in the property as in the following example:

<property name="eventAggregateMaxHorizon_defvarTotalSessionRatings">P30D</property>

Where the event time horizon is set to 30 days for the TotalSessionRatings global aggregate.