Mango Rollups and Statistics
Rollups and statistics are the mechanisms Mango uses to summarize raw point value data into meaningful aggregated metrics. Rollups produce quantized time-series data (e.g., hourly averages), while statistics produce summary metrics for an entire time range (e.g., the maximum temperature over the past week).
Rollups
A rollup operation divides a time range into equal intervals and computes a statistic for each interval. For example, requesting an average rollup for the past day with 1-hour intervals returns 24 entries, each containing the hourly average.
How Rollups Handle Missing Data
- If no data is present in a period, some statistics will be empty while others that depend on the previous value will still compute.
- Some statistics use one value before and one value after the period when they are available. This continuity is important for accurate charting and for statistics like Average (which is time-weighted).
Note: REST API calls with rollups return all timestamps as the period start time. To get the actual timestamps for individual statistics, use the statistics endpoint instead.
Numeric Rollups
The following rollup types are available for Numeric data points:
| Rollup | Description |
|---|---|
| None | No rollup; returns raw values |
| Average | Time-weighted average of the start value and all values in the period. Takes into account how long each value was held. |
| Arithmetic Mean | Simple (non-time-weighted) arithmetic mean of all values in the period. Does not account for how long each value was held. |
| Count | Number of sampled or logged values within the period |
| Minimum | Smallest value in the period, including the start value |
| Minimum in Period | Smallest value strictly within the period (excludes the start value) |
| Maximum | Largest value in the period, including the start value |
| Maximum in Period | Largest value strictly within the period (excludes the start value) |
| Sum | Total of all values in the period. Does not count the start value unless it occurred exactly at the period start. |
| First | First sampled or logged value within the period |
| Last | Last sampled or logged value within the period |
| Start | The value before or exactly at the start of the period |
| Delta | Change in value within the period. With no values and no start value: NaN. With a start value but no values: 0. |
| Accumulator | Last value minus the previous (start) value. Useful for counter/totalizer points. |
| Integral | Time-weighted integral of values over the period, considering the start value. Represents the area under the curve. |
Average vs. Arithmetic Mean
The Average rollup is time-weighted: if a value of 10 was held for 50 minutes and then changed to 20 for the remaining 10 minutes, the average is (10 * 50 + 20 * 10) / 60 = 11.67, not (10 + 20) / 2 = 15. Time-weighted averages are correct for physical signals where the value persists until it changes.
The Arithmetic Mean is a simple average of all logged values regardless of how long each was held. It is appropriate when you have regularly spaced samples and want a non-weighted average.
Non-Numeric Rollups
The following rollup types are available for Alphanumeric, Binary, and Multistate points:
| Rollup | Description |
|---|---|
| None | No rollup; returns raw values |
| Count | Number of sampled or logged values within the period |
| First | First value in the period |
| Last | Last value in the period |
| Mode | Most common value in the period |
| Runtime | Total time spent in each state during the period |
| Proportion | Proportion of time in each state relative to total time in any state (not necessarily the entire period) |
| Starts | Number of times each state was entered during the period |
Statistics
Mango can compute a set of statistics for a data point over any time range. The set of statistics returned depends on the data type of the point.
Analog Statistics (Numeric Points)
| Statistic | Description |
|---|---|
| Average | Time-weighted average over the period |
| Minimum | Smallest value in the period (including start value) |
| Maximum | Largest value in the period (including start value) |
| Sum | Total of all values in the period |
| Count | Number of values in the period |
| First | First value and its timestamp |
| Last | Last value and its timestamp |
| Delta | Change from start to end of the period |
| Accumulator | Last value minus the start value |
| Integral | Time-weighted integral over the period |
| Start | Value at or before the start of the period |
Starts and Runtime List (Binary and Multistate Points)
| Statistic | Description |
|---|---|
| First | First value and timestamp in the period |
| Last | Last value and timestamp in the period |
| Count | Number of values in the period |
| Starts and Runtimes | For each state observed during the period: |
| - Runtime | Total time in that state |
| - Proportion | Time in that state as a fraction of total time in all states |
| - Starts | Number of times that state was entered |
Value Change Counts (Alphanumeric and Image Points)
| Statistic | Description |
|---|---|
| First | First value and timestamp in the period |
| Last | Last value and timestamp in the period |
| Count | Number of values in the period |
| Changes | Number of value changes during the period |
Using Rollups via the REST API
The REST API supports rollup queries on the point values endpoint:
GET /rest/latest/point-values/{xid}?from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z&rollup=AVERAGE&timePeriod=HOURS&timePeriods=1
This returns hourly averages for the specified point over a one-day range.
Common query parameters:
| Parameter | Description |
|---|---|
rollup | The rollup type (AVERAGE, MAXIMUM, MINIMUM, SUM, COUNT, DELTA, etc.) |
timePeriod | The period type (SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, YEARS) |
timePeriods | The number of periods per interval |
truncate | When true, rounds the from/to times to clean period boundaries |
Best Practices
- Use Average for continuous analog signals (temperature, pressure) to get representative values for each period.
- Use Delta for counter/totalizer points (kWh meters, water meters) to see consumption per period rather than the running total.
- Use Maximum or Minimum to identify peak or trough values for capacity planning or alarm threshold tuning.
- Use Integral for energy calculations where you need the area under a power curve (kW integrated over time gives kWh).
- Choose rollup intervals that match your analysis needs. Hourly rollups over a month produce 720 data points -- manageable for charts. Minute-by-minute rollups over a year produce over 500,000 data points and will be slow.
Related Pages
- Rollup UI Component — Configure rollup controls in the date bar and per-point default rollups
- Watch List Charts — Apply rollups and the Simplify algorithm when charting data points
- Creating Excel Reports — Use rollups in Excel report time period configurations
- Data Point Properties Reference — Set default rollup type and period on individual data points
- Data Point and Logging Settings — Understand how logging type affects which values are available for rollup calculations