Aggregate Processor

Overview

Aggregate Processor splits an interval into periods and calculates statistics for each period. If no period is specified in the request, statistics are computed for the entire interval.

The aggregation process is implemented as follows:

  1. Load detailed data within the specified startDate and endDate into each series separately.
    startDate is inclusive and endDate is exclusive.
  2. Split each series time:value array into periods based on an alignment parameter.
    If period parameter is not specified, all series data belongs to a single period from startDate until endDate.
  3. Discard periods whose start time is earlier than startDate.
  4. Apply statistical function to values in each period and return a modified time:value array for each series where time is the period start time and value is the result of the statistical function.

Fields

Name Type Description
type string [Required] Statistical function applied to detailed values in the period, such as AVG, SUM, or COUNT.
types array Array of statistical functions.
Either type or types field are required in each query.
period object Regular period specified with count and time unit, for example { "count": 1, "unit": "HOUR" }.
interpolate object Fill values in empty periods using an interpolation function such as PREVIOUS or LINEAR.
threshold object Object containing the minimum and maximum range for THRESHOLD_* functions.
calendar object Calendar settings for THRESHOLD_* functions.
workingMinutes object Working minutes settings for THRESHOLD_* functions.
order integer Controls the processing sequence of the group, rate and aggregate stages. The stage with the smallest order is executed first. If the stages have the same order, the default order is: group, rate, aggregate.
Default: 0.

Period

Period is a repeating time interval used to group detailed values within some timespan to apply a statistical function.

Name Type Description
unit string Time unit such as MINUTE, HOUR, DAY.
count number Number of time units contained in the period.
align string Alignment of the period start/end time.
Allowed values: CALENDAR, START_TIME, END_TIME, FIRST_VALUE_TIME.
Default: CALENDAR.
timezone string Time Zone ID for aligning timestamps in CALENDAR mode.
The default value is equal to the database time zone displayed at Settings > System Information.

Example: { "count": 1, "unit": "HOUR" } or { "count": 15, "unit": "MINUTE", "align": "END_TIME" }.

calendar

Name Type Description
name string Custom calendar name

Example: { "name": "au-nsw-calendar" }.

threshold

  • Either min or max is required.
Name Type Description
min number Minimum threshold.
max number Maximum threshold.

Example: { "max": 80 } or { "min": 100, "max": 150 }.

Working Minutes

Name Type Description
start number [Required] Working date start time, in minutes. If working day starts at 9:30 then start can be specified as 570 (9 * 60 + 30).
end number [Required] Working date end time, in minutes.

Examples

  • 1-hour Average
{
    "aggregate" : {
        "type": "AVG",
        "period": {"count": 1, "unit": "HOUR"}
    }
}
  • 15-minute Average and Maximum
{
    "aggregate": {
        "types": [ "AVG", "MAX" ],
        "period": { "count": 15, "unit": "MINUTE" }
    }
}
  • Average and Count for the Entire Interval
{
    "aggregate": {
        "types": [ "AVG", "COUNT" ]
    }
}

Interpolation

By default, if the period does not contain any detailed values, the period is excluded from results.

Configure this behavior with an interpolation function which fills a missing period with data calculated based on previous and next period aggregate values.

Note that missing period values are interpolated from aggregate values of neighboring periods and not from raw values.

Interpolation Fields

Name Type Description
type string [Required] Interpolation function.
value number [Required by value function] Constant number used to set as the value for empty periods.
extend boolean Add missing periods at the beginning and end of the selection interval.
Default: false.

Values added by the extend setting are determined as follows:

  • If the VALUE {n} interpolation function is specified, the extend option sets empty leading and trailing period values equal to {n}.
  • Without the VALUE {n} function, the extend option adds missing periods at the beginning and end of the selection interval using NEXT and PREVIOUS interpolation functions.

Interpolation Functions

Type Description
NONE No interpolation. Periods without raw values are excluded from results.
PREVIOUS Set value for the period based on the previous period value.
NEXT Set value for the period based on the next period value.
LINEAR Calculate period value using linear interpolation between previous and next period values.
VALUE Set value for the period to a specific number.

Examples

PREVIOUS:

"aggregate" : {
   "type": "AVG",
   "period": {"count": 1, "unit": "HOUR"},
   "interpolate" : {
      "type": "PREVIOUS"
   }
}

LINEAR:

"aggregate" : {
   "type": "AVG",
   "period": {"count": 1, "unit": "HOUR"},
   "interpolate" : {
      "type": "LINEAR"
   }
}

VALUE WITH EXTEND:

"aggregate" : {
   "type": "SUM",
   "period": {"count": 1, "unit": "HOUR"},
   "interpolate" : {
      "type": "VALUE",
      "value": 0,
      "extend": true
   }
}

Additional Interpolation Examples

ChartLab Examples

Interpolation Example