The Advanced AF SDK lab at UC SF 2017 was on this very topic. The material in this 9-part series follows much of that lab which showcases AFEventFrameSearch methods new to PI AF SDK 2.9.
Blog Series: Aggregating Event Frame Data
Part 9 - Conclusion
We covered a lot of ground in this 9-part series because a lot of what was being covered was new ground. You were introduced to 4 brand new methods to PI AF SDK 2.9. Three of those were aggregation methods, which has got to be a much welcomed feature in AFEventFrameSearch. And FindObjectFields might be the first one any developer checks out for its sheer speed and versatility not just for aggregation but for lightweight detail reporting. To rehash what was covered:
- Part 4 We showed the old way of doing things with the classical FindEventFrames. This provided a baseline in performance for us to benchmark against the other new methods.
- Part 5 We saw the new lightweight FindObjectFields method to return a skinny set of columns. We looked at all 3 overloads of this method, each of which is concerned about casting first from generic object to the specific underlying type, followed perhaps by additional casting or converting to the type you desire.
- Part 6 We saw the Summary method and discovered there is an event weighted overload as well as a general weighting overload to produce custom weightings beyond just time weighted.
- Part 7 We saw how to use the GroupedSummary method to summarize with groupings, which allowed us to make fewer calls.
- Part 8 We finished off with showing how to use a compound AFSummaryRequest to produce a 2-level grouping. It was a tad bit complicated but did have great performance.
Tips to Remember
- Use CaptureValues() to see the performance benefits from server-side filtering.
- Classes inherited from AFSearch, such as AFEventFrameSearch, now implement IDisposable starting with AF SDK 2.9. You should consider wrapping your calls inside a using block, or else issue an explicit Close() when you are finished with your search activities.
- When composing a query string, any values containing embedded blanks should be wrapped inside single or double quotes.
- Your time string for output queries should be output using the "O" Round-trip specifier.
- For best performance, you probably want to choose the method that makes the fewest calls to the server.
- If you are working with detail records, you should strongly consider including ID as one of the input fields. That way if you ever have the need to perform further drilling into a specific event frame, you have the unique ID which can help you quickly locate the full event frame in question.
- There is no weighted overload for FindObjectFields. You would be expected to include your own weighting field (e.g. Duration or custom) in the returned set of values.
- The underlying type of any attribute's value will be AFValue.
- You may use fields or properties for your DTO class.
- For the auto-mapped overload, you will have to use the ObjectField decorator to map the source attribute name that happens to begin with a "|" to your desired DTO field name.
- For event frame properties and the auto-mapped overload, the default is to use the same property name for the mapping. However, you may override this default.
- Is limited to no more than 2 levels of groupings.
- For 1 grouping level, you should just use Summary or GroupedSummary depending upon your needs since these are less complicated and have a simpler packaging of the results.
- Based on previous bullets, you probably would only use AFSummaryRequest precisely when you need 2-level groupings.
Other than showing the method names in Part 1, we did not mention any of the async methods or show their usage. But they are there and easily discernible by seeing a CancellationToken among the parameters. Once LiveLibrary is active for PI AF Client 2017, you are encouraged to review the online help for:
- SummaryAsync (both event and general weighting overloads)
If you are curious as to why FindObjectFields does not have an async counterpart, keep in mind that FindObjectFields makes paged calls. You are always capable of break your processing, which will stop requests for more pages of data.
While the more natural weighting with the data archive is probably time weighted, event frames are not stored in the data archive but rather in SQL Server. It should be no surprise that event weighting is the more natural or default weighting when dealing with event frames. Out of the new AFEventFrameSearch aggregation methods, only Summary and SummaryAsync offer some other weighting overload other than event weighted. You aren't limited to just time weighted as the lone alternative. The new overloads are flexible to allow custom weightings.
FindObjectFields doesn't allow for weightings because it's not an aggregation method. You may still use FindObjectFields but you should include the weighting field as part of the set of skinny columns to be returned.
I did not show any examples of binning. That might be a future topic. But you should be aware that these methods exist.
- For discrete values such as integers or strings, FrequencyDistribution and FrequencyDistributionAync generates a <gasp> frequency distribution.
- For floating point values, you would want to bin by ranges. See Histogram or HistogramAsync for that. Note that your requested ranges do not have to be in evenly-spaced intervals.
- Why not have summaries by bins? For this there is the BinnedSummary and BinnedSummaryAsync methods.
This is the End?
Or is it? Don't be surprise if I do a future series about binning.
Thanks for reading the series. I hope you enjoyed it. Please remember to use this knowledge for good and not evil.