Aggregates and rollups

Reading every raw value of a year would be slow and would not fit on a chart. Hermetry therefore summarises numeric readings per minute, hour and day, and reads the summary that fits the window you ask for. This page explains the summaries, how the resolution is chosen and what each aggregate function returns.

The summaries

For every numeric key of every device, the store keeps five figures per bucket:

Figure	Meaning
sum	The sum of the values in the bucket
count	How many values arrived in the bucket
min	The smallest value
max	The largest value
last	The value with the latest timestamp in the bucket

Level	Bucket	Kept for
1-minute aggregates	1 minute	Your retention class, at most 31 days
Hour rollups	1 hour	Your full retention class
Day rollups	1 day, midnight to midnight UTC	Your full retention class

All buckets are aligned to UTC. The minute summaries are computed by a job that runs every minute; the hour and day rollups are derived from them. A reading that arrives after its minute was summarised marks that minute again, so late readings are included. A freshly stored reading can take a minute or two to appear in summaries; raw reads (windows up to 24 hours) see it at once.

Text, true/false and JSON values are not summarised. See Numbers, text and true/false values.

Which resolution a window reads

With the bucket auto (the default for charts and the API):

Window length	Resolution
Up to 24 hours	Raw values, every reading
Up to 10,000 minutes (about 6.9 days, so a full 7-day window already reads hours)	1 minute
Up to 10,000 hours (about 416 days)	1 hour
Longer	1 day

A window may hold at most 10,000 buckets at the chosen resolution. If you ask for a fixed resolution that would need more (for example 1m over 30 days), the API answers 400 with the code range_too_large. Ask for a coarser bucket or a shorter window.

A window that reaches further back than a level is kept returns nothing for the missing part. For example, with the 365-day class, 1m buckets older than 31 days are gone; ask for 1h instead.

The aggregate functions

Each bucket returns one value, computed from its five figures:

Function	Value per bucket	Use it for
avg (default)	sum / count	Temperatures, levels, pressures
min	The smallest value	Lowest level, coldest point
max	The largest value	Peaks, “did it happen” for 0/1 keys
last	The last value	Meter readings, states, setpoints
sum	The sum of the values	Values that are already per-interval amounts (litres in this interval, events as 1)
count	The number of readings	Reporting rate, data completeness
increase	How much a counter rose	Energy and water meters, pulse totals

avg is a plain average of the readings in the bucket, not weighted by time. A device that reports more often in some periods weighs those periods more.

When a raw window is read (up to 24 hours), the aggregate is not applied: you get every stored value. Charts that show raw points and a summary side by side can therefore show more detail for the last day than for older days.

increase, for counters

Counters only grow (kWh, m³, pulses) until they restart from zero. increase turns them into consumption per bucket:

• Each bucket’s value is its last minus the previous bucket’s last.
• If the value went down (the counter restarted), the bucket’s last is taken as the rise, counting from zero.
• The first bucket of the window counts what rose inside it: its last minus its min.

Example with hourly buckets of an energy meter:

Hour	last	increase
08:00	1,200.0	4.0 (first bucket: last 1,200.0 – min 1,196.0)
09:00	1,212.5	12.5
10:00	1,221.0	8.5
11:00	3.0	3.0 (the meter restarted)

Notes:

• A rise across a gap is counted in the first bucket after the gap.
• A counter that restarts and then rises above its old value within one bucket is not seen as a restart.
• Use increase on the raw counter, never on a key that is already a per-interval amount; use sum for that.

Using the summaries

Where	How you choose
Dashboard chart cards	The card’s Aggregate setting and the board’s time window. See Chart cards and Data sources and parameters.
The device’s Telemetry tab	Always avg, with the window you pick. See The device’s Telemetry tab.
The API	bucket and agg on GET /api/telemetry/series. See The history API.
Flows	The Statistics block computes figures over a message window in the flow itself. See Counters, statistics and watchdogs.

Local days and months

Day rollups are UTC days. For a daily total in another time zone, read 1h buckets and add the hours of each local day yourself; for zones with a half-hour offset, read 1m buckets (up to 31 days back). See the example in The history API.