Aggregate Event

POST https://octave-api.sierrawireless.io/v5.0/{company}/event/aggregate

Event data within a Stream can be grouped and aggregated in powerful ways.

For example:

• Get the average wind speed in the last 10 minutes, by town
• Get the maximum temperature within 5 miles of New York City
• Get the percentage of sensors that are currently online

Event Aggregate calls can be made through the REST API and within the Cloud Action environment. The examples below use the REST interface as a convention. However, the same information can be retrieved by a Cloud Action by using the JavaScript function Octave.Stream.Event.aggregate.

Selectors

Functions that wrap an Event element.

Dates

For any field that is specified as a date, you can use a Date Selector to retrieve part of that date. This can be useful for grouping purposes.

The selectors are:

• $year
• $month
• $day
• $hour
• $minute
• $second

Example: $month:lastEditDate will return only the month component from the date. Use this to group results by the month they were last edited.

By omitting the element name, creationDate will be automatically chosen. E.g. $year returns the year the Event was created.

Aggregate

Specifies an aggregation function applied to a field.

• $sum:field The sum of the field values for the defined grouping
• $avg:field The average value of the field for the defined grouping
• $unique:field A list of unique values for the field within the defined grouping
• $max:field The maximum value of the field for the defined grouping
• $min:field The minimum value of the field for the defined grouping
• $all:field All values of the field for the defined grouping, includes duplicates
• $count matching count of found records.

Distance

If you have specified a rule element that utilizes a location, e.g. x : location WITHIN 20 MILES of [123,-321], you can use the distance selector distance:x to retrieve the distance this Event is from [123,-321].

This can be used to sort or group the results, or as a general output.

For example, if there was a Stream that contained Events indicating the processor's temperature as a 'cpu_temp' elem, in order to obtain the average, minimum and maximum temperatures on a monthly basis:

• "filter":"EXISTS cpu_temp" This uses a sample set which ensures that all Events selected for this aggregate query contain a cpu_temp, all others will be excluded.
• "rules":{"x":"cpu_temp > 50"} This specifies a rule to define how often the cpu_temp is above the ideal temperature, in this case 50.
• "groupBy":["$month"] I want the response to provide numbers on a monthly basis.
• "output":["$avg:cpu_temp","$min:cpu_temp","$max:cpu_temp","$avg:x","$count"] Here the maximum, minimum, and average temperature values will be returned in the grouping for each month. The last data point in the output, $avg:x, will return the percentage of Events that pass the rule that was defined in rules. $count will return the size
  of the sample set of Events that satisfied the filter within each grouping.
• "sorts":["$avg:x:desc", "$avg:cpu_temp:asc"] The results will be sorted by the $avg:x field in descending order first, then by the $avg:cpu_temp field in ascending order.