Aggregations

An aggregation is responsible for providing analysis of a larger dataset, to make it more manageable. While it would be possible to plot millions of samples in a single graph, it is simply not practical. Aggregations give the mean to further aggregate the samples stored in the database.

An aggregation can be defined either in JSON, or HQL. For each aggregation, both forms will be displayed below.

Size and Extent

The size of an aggregation determines the frequency that data occurs in the resulting aggregation. So a size of two minutes would cause an aggregation to output a series that has a sample, every two minutes.

The extent of an aggregation determines how wide a single sample will load data in time. So an extent of one hour would cause each sample to be the result of aggregating the last hour of data.

Combining size and extent, we now have a flexible system for describing how to build a dataset suitable for plotting.

The following graphics represents what data will be sampled to generate the sample at point 2. The blue bar is the extent, and the red bar is the size.

The next point we'll sample for is 3. This applies the same principle as above.

Aggregating on Resource Identifiers

Resource Identifiers are not currently included in the Suggest index, and thus do not appear in suggestions. Resource Identifiers can still be used in aggregations by adding them free-form.

Average Aggregation

JSON

{"type": "average", "sampling": {"unit": <unit>, "value": <number>}}
HQL

average(size=<duration>)
Description

The average aggregation takes all samples in a given extent, and calculates the average value over them.

Chain Aggregation

JSON

{"type": "chain", "chain": [<aggregation>, ..]}
HQL

<aggregation> | ..
Description

A chain aggregation applies the specified aggregations in order. The result of the first aggregation is fed into the second, and so forth.

Count Aggregation

JSON

{"type": "count", "sampling": {"unit": <unit>, "value": <number>}}
HQL

count(size=<duration>)
Description

The count aggregation calculates the number of all samples in a given extent.

Delta Aggregation

JSON

{"type": "delta"}
HQL

delta()
Description

The delta aggregation calculates the difference between samples in a given extent.

It's intended to be used with gauges and can produce negative values.

Delta per Second Aggregation

JSON

{"type": "deltaPerSecond"}
HQL

deltaPerSecond()
Description

The delta per second aggregation calculates the difference per second between samples in a given extent.

It's intended to be used with gauges and can produce negative values.

Rate per Second Aggregation

JSON

{"type": "ratePerSecond", "sampling": {"unit": <unit>, "value": <number>}}
HQL

ratePerSecond()
Description

The rate per second aggregation calculates the rate per second between samples in a given extent.

Rate per second works with sampling. If a queries resolution is 1 minute and points are published every 30s each bucket will contain 2 points. The rate will be calculated by getting the difference between the two points values and dividing them by the time between the points.

Note: at least 2 points are required in order to calculate the rate. Otherwise the previous value is unknown.

It's intended to be used with cumulative counters. It will handle the counters being reset because of restarts, etc.

Max Aggregation

JSON

{"type": "max", "sampling": {"unit": <unit>, "value": <number>}}
HQL

max(size=<duration>)
Description

The max aggregation picks the largest numerical value seen in the given extent.

Min Aggregation

JSON

{"type": "min", "sampling": {"unit": <unit>, "value": <number>}}
HQL

min(size=<duration>)
Description

The min aggregation picks the smallest numerical value seen in the given extent.

Not Negative Aggregation

JSON

{"type": "notNegative"}
HQL

notNegative()
Description

The not negative aggregation filters out negative values from all samples in a given extent.

Standard Deviation Aggregation

JSON

{"type": "stddev", "sampling": {"unit": <unit>, "value": <number>}}
HQL

stddev(size=<duration>)
Description

The standard deviation aggregation calculates the standard deviation of all samples in a given extent.

Sum Aggregation

JSON

{"type": "sum", "sampling": {"unit": <unit>, "value": <number>}}
HQL

sum(size=<duration>)
Description

The sum aggregation sums the values of all points in a given extent.

Sum Squared Aggregation

JSON

{"type": "sum2", "sampling": {"unit": <unit>, "value": <number>}}
HQL

sum2(size=<duration>)
Description

The sum squared aggregation sums the squared values of all points in a given extent.

TopK/BottomK/AboveK/BelowK Aggregation

JSON

{"type": "topk", "k": <number>}
{"type": "bottomk", "k": <number>}
{"type": "abovek", "k": <number>}
{"type": "belowk", "k": <number>}
HQL

topk(<number>)
bottomk(<number>)
abovek(<number>)
belowk(<number>)

These are a set of filtering aggregations. A filtering aggregation reduces the number of result groups according to some criteria.

  • TopK - Picks the largest time series
  • BottomK - Picks the smallest time series
  • AboveK - Picks the time series that has values above the given threshold
  • BelowK - Picks the time series that has values below the given threshold

Points Above/Below Aggregation

JSON

{"type": "pointsabove", "threshold": <number>}
{"type": "pointsbelow", "threshold": <number>}


pointsabove(<number>)
pointsbelow(<number>)

These aggregations reduce the number of datapoints returned per series. Only datapoints matching the criteria will be returned, all others will be dropped.

  • PointsAbove - Return only datapoints above the given threshold
  • PointsBelow - Return only datapoints below the given threshold