--- title: Aggregations ---

{{ page.title }}

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 change between samples in a given extent.

Delta per Second Aggregation

JSON

{"type": "deltaPerSecond"}
HQL

deltaPerSecond()
Description

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

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.