GeoEvent 10.9: Introducing Choice Elements
When would I use a choice element?
The choice element is intended to replace situations where multiple filter elements are deployed in parallel (see Figure 1).
Figure 1 – Parallel filtering paradigm
This parallel filtering paradigm is an anti-pattern that should be avoided when possible. The reason for this is two-fold:
- Each filter element must get its own copy of an event for it to evaluate the conditional statement. Every filter element added to a parallel filter design requires an additional copy of each event be made. Therefore, the system will see a linear increase in event traffic in the parallel filtering section of the GeoEvent Service for every additional parallel filter added.
- Each event is evaluated against the conditional statement of each filter independently. This creates a linear increase on the CPU load in the parallel filtering section of the GeoEvent Service for every additional parallel filter added.
Unfortunately, up until the 10.9 release, it was hard to avoid parallel filtering in many cases because of the singular nature of the filter element. Service designers were left with no options when events were required to be routed across several processing paths. These situations were prevalent in several domains including (but not limited to):
- Asset Types: processing specific assets according to their type (trucks, cars, busses, taxis, ride-share, recreational, commercial, public, etc.).
- Field Values: a geometry might be non-existent, null, present, inside or outside a specified location. A field value may be above, between or below a specified set of threshold values.
- GeoEvent Definitions: An input may emit multiple GeoEvent Definitions that require separate processing paths.
Choice elements were designed to replace a filter element whenever more than one conditional statement must be evaluated in a specific route of a GeoEvent Service. In the simplest case you may need to route events that pass a filter to one processing path, and all other events to another pass. This pattern is known as an “If … Else”. A more complex use case may need to route multiple different GeoEvent Definitions to their own dedicated processing path. Fundamentally, any time more than one filter element is used in parallel, it is a good candidate for replacing with a choice element.
How do choice elements work?
As mentioned above, a choice element specifies a list of routes a GeoEvent could take. Each route is evaluated by a when clause that defines the conditional statement an event must meet to pass through. If an event passes the condition defined by the when clause, it follows that route. If an event does not pass the condition defined by the when clause, it passes to the next when clause if one exists. The when clauses in a choice element are processed in a serial order, as defined in the choice element.
If an event record does not meet any of the conditions specified in the when clause(s), it can optionally be passed to an otherwise route. If an otherwise route is enabled, the event is passed to that route, there is no condition that must be met. If an otherwise route is not enabled, the event record is dropped and is not passed to any route.
Figure 2 below shows an example of a choice element as it is displayed on the GeoEvent Server service designer canvas. It also shows how events are processed inside of the choice element.
Figure 2 – Example choice element and conceptual event flow process diagram.
The implementation of the choice element does not create extra copies of an event for each conditional statement to evaluate. The original event is evaluated against each conditional statement in sequential order, eliminating extra events on the message bus. In addition, once an event passes a given conditional statement, it is no longer considered for the following statements, reducing the compute load on the system. The combination of these changes results in a choice element that does not degrade performance of the system as more conditional statements are added (see Figure 3 below).
Figure 3 – Choice element vs filter element performance
Optimizing a choice element
One observation about a choice element that is important to understand is an event record that meets the condition in a given when clause will not be considered for any subsequent when or otherwise routes. In the example below (figure 4), events of type ‘A’ will not be considered in the second conditional statement looking for events of type ‘B’.
Figure 4 – Example choice element
Sometimes Performance Cannot Be Optimized
It is important to note that the optimization strategy presented in this section may not be applicable to all choice elements. Sometimes, a when statement must be evaluated before the other statements because the conditions may overlap. An example of this (see figure 5) would be a choice element that routes vehicle events based on vehicle type and vehicle owner. If a vehicle is owned by the city, it should be processed in a separate route from the other vehicle types. In this case, it would not be possible to move the vehicle owner condition further down the list because it would never receive any data (assuming the city only owns cars, trucks, buses, and boats).
Figure 5 – Example choice element that cannot be re-ordered/optimized
Re-ordering for Optimization
If your conditions are able to be re-ordered (they don’t have any overlapping conditions), it is important to order the when statements in the order they are statistically likely to occur. The first conditional statement should pass the most events, the second conditional statement should pass the second-most events, and so on. For the example in figure 4 above, a distribution of the expected event frequency is displayed in figure 6.
Figure 6 – Optimized choice element
If the event frequencies did not match this pattern, then the choice element's when clauses should be re-ordered in such a way that the event distribution met this pattern. Figure 7 displays an event frequency distribution that is not optimized on the left. In this case, the choice element’s when clauses should be re-ordered so that they are evaluated in the order displayed on the right.
Figure 7 – Reorder to optimize a choice element
Moving the Otherwise Up Front
If you find yourself in the situation where most of the events entering a choice element are exiting via the otherwise route, you should consider devising a when clause that you can put in the first evaluation slot that will identify these events before they are passed to the rest of the conditional statements. An example of this is displayed below in figure 8.
Considerations when working with choice elements
There are many considerations when working with a choice element, including:
At least one conditional statement
Every choice element must have at least one when clause. A choice element with one when clause and the optional otherwise route disabled is functionally equivalent to a filter element.
Otherwise is optional
The otherwise route is optional. If an event does not pass the provided conditional statements in the choice element's evaluation section it is passed to the otherwise. If the otherwise is enabled, the event is allowed to pass through to the otherwise route. If the otherwise is not enabled, the event is dropped.
Each choice element must have one or more parent elements
Each choice element must have at least one parent element and that parent element must be either an Input element, a filter element, or a Processor element. A choice element can have multiple parent elements.
A choice element’s parent cannot be another choice element
A choice element cannot route to another choice element; meaning two choice elements cannot be placed in a row in a GeoEvent Service:
- The input to a choice element cannot be the output of another choice element.
- The target of a choice element cannot be another choice element.
If a use case requires the target of one choice element be routed to a second choice element, use a No Operation Processor element in between the two choice elements. An alternative is to include the when clause(s) from the second choice element into the first choice element. Figure 9 shows the issue and both methods for getting around the issue.
Figure 9 – Working around back-to-back choice elements
Working with choice elements in a GeoEvent Service
Adding a choice element to a GeoEvent Service
To add and configure a choice element in a GeoEvent Service, follow the steps below.
1. In the service designer, drag and drop a choice element from the New Elements list onto the canvas. The choice element dialog will open.
2. Enter a Name for the new choice element.
In a choice element, one or more conditional statements can be applied, in a specified order, to the event data. Each conditional statement has a unique name that identifies it as well as a number (starting with 1) that indicates the order in which the conditional statements will evaluate the event data.
3. Click Add to add a conditional statement.
4. In the Choice Properties dialog, follow the steps below to add a when clause.
- Enter a Name for the conditional statement.
- Click Add Expression
to add and configure a when clause.
- Click Add Expression
again to add and configure additional when clause(s).
- Click Ok to save the conditional statement.
5. Repeat steps 3 and 4 above to add additional conditional statements, as necessary.
6. Optionally, check the Otherwise checkbox to define an otherwise route.
- Checking the Otherwise checkbox enables an otherwise route. All events that do not meet the criteria defined by the when clause(s) will be passed to the otherwise route.
- Unchecking the Otherwise checkbox means any event records not passing the defined when clause(s) will be dropped.
7. Click Ok to save and add the choice element to the service designer canvas.
8. Connect the choice element to the other elements in the GeoEvent Service.
Edit a choice element
The choice element dialog provides options to review, edit, delete, and reorder configured conditional statements.
- Hover over
to view the when clause(s) associated with a conditional statement.
- Click
to open and edit a conditional statement’s when clause(s).
- Click
to delete a conditional statement.
- Use
to adjust the order the conditional statements evaluate the event data.
Using filters in when clauses
In a when clause, you have the option to use different types of filters to evaluate the event data. For details on the different types of filtering options, see the resources below.