Aggregation of events and entities over time

Decision Server Insights can compute an aggregated value from distributed data.

Aggregation of events can be specified at a global level and a shared level. A global event aggregation is evaluated automatically when a new event of that type occurs. A shared aggregate computes simple results (count, min, max, average, total) from an event type to instantiate an attribute of an entity. A shared aggregate has its own state, which is different from the state of a rule agent.

Rules can also access aggregated data from past events that are processed by the same agent. You can use variables that point to an event attribute over time to make conditions and decisions in rules. For example, in the following rule three variables are defined to aggregate the total amount of all purchases up to a time point.

definitions  
set 'first amount' to the total amount of all purchases of the trader before or at 5/1/2015;  
set 'second amount' to the total amount of all purchases of the trader before or at 6/1/2015;  
set 'third amount' to the total amount of all purchases of the trader before or at 7/1/2015;
if ... 
then ...

However, using a shared aggregate in rules to calculate a value from past events is more efficient than using unique variables. Using the previous example, a single shared aggregate can be written to aggregate the amount from purchase events of a trader.

the cumulated amount of a trader is aggregated from purchases, 
   where this trader comes from the buyer of each purchase as the total amount of purchases
available for 1 year

The shared aggregate does not contain the conditions before or at 5/1/2015, before or at 6/1/2015, and before or at 7/1/2015. Rules in multiple agents can query the shared aggregate at any time point or period within the available period. An example rule that uses a shared aggregate looks similar to the use of an event attribute; the difference is that each local variable uses the same shared aggregate.

definitions 
set 'first amount' to the cumulated amount of the trader at the time of 5/1/2015; 
set 'second amount' to cumulated amount of the trader at the time of 6/1/2015; 
set 'third amount' to the cumulated amount of the trader at the time of 7/1/2015;
if ... 
then ...

A global entity aggregate is evaluated on a schedule or when explicitly recalculated by an agent, an MBean, or a script. The runtime environment identifies the global aggregate computation as a job.

The following figure shows the steps that are involved in Insight Designer to create and use a global entity aggregate and a global event aggregate in your solution. When the solution is deployed, you can retrieve the values of both aggregate types by using REST, agents within your solution, or the JobManagerMXBean.

Global entity aggregates

An entity aggregate is a calculation of the number of (count) of an entity across all instances of an entity type, or a selected subset of the instances of an entity type. An entity aggregate can also apply to the values of the properties of entities, for example the total salary of all Employees.

In the following rule, flight is an entity type with a property named scheduled arrival time and a property named actual arrival time.

define 'number of delayed flights this month' as the number of flights , 
where the actual arrival time of each flight is after 15 minutes after the scheduled arrival time of each flight and the actual arrival time of each flight is during the current month, 
evaluated every day at 2:19:23 PM

All rule agents that reference the flight entity type in a rule condition have read-only access to the variable number of delayed flights this month.

Note: An entity aggregate can be recalculated by rule agents, Java™ agents, and predictive agents.

Global event aggregates

An event aggregate is a calculation of the number of (count) of an event across all instances of an event type, or a selected subset of the instances of an event type. Similar to entity aggregates, an event aggregate can also apply to the values of the properties of events.

As events are received and processed, the event values are combined to create a global aggregate value (integer or double). All global aggregates are stored in the primitive double data type for reasons of consistency.

Event aggregates can operate only over the data of a single event type and cannot refer to data in entities.

Note: Decision Server Insights receives events continuously, and creates and updates entities as a result of these events. For this reason, an aggregate is representative of a snapshot of the system at a particular point in time. Consistency of an aggregate across the system is only possible when no events that affect its value are being processed, and no failures occur.

In the following rule definition, the event type is delayed flight events. All rule agents that reference the BOM project have read-only access to average flight delay this month in their rule conditions. Java agents can retrieve the values of event aggregates by using the Java API.

define 'average flight delay this month' as the average delay time of all delayed flight events, 
where the date of each delayed flight event is during the current month

Shared aggregates

You can use a shared aggregate to make a business decision.

The aggregate is generated and shared with any agent that is bound to the entity.
The entity attribute must be defined in the business model definitions.
The nature of the shared aggregation is defined in the statements of the business model.
The available for <time duration> construct determines for how long event data is available for aggregation.
The resolution combines the data of multiple events over its specified period. A resolution can significantly reduce the time to calculate the aggregate value.

A shared aggregate is somewhat like an index of a database; it can be used to access quickly any value within the range of the horizon. Getting a value at a specified moment in time (not necessarily the current moment) can be used to detect when a change in the value occurs over time.

The following figure shows the steps that are involved in Insight Designer to create and use a shared aggregate in your solution. When the solution is deployed, you can retrieve the values of the aggregate by using REST, the agents within your solution, and Java clients.

If you always want to query the event-related aggregate over the same time period, a day or a week for example, use a where statement in the shared aggregate definition to limit the events to a specified period (and number). Rules can set a time point (or use the agent variable now) from which to calculate the result. A decision can be made for example if this value is up or down compared to a previous period or time point.

If you want to query the event-related aggregate over different time periods, use rules to specify the time period and the number of events from which to calculate the result. A decision can be made in rules for example if this value is up or down compared to a different period.