Skip to content

IoT Times Series Aggregates Service

Idea

The IoT TS Aggregates Service is used to read aggregated interval data that is being calculated based on raw time series data. The IoT Data Services solution automatically creates aggregated summaries of all numeric time series data. This allows applications to retrieve smaller data sets that cover a longer period of time with much better performance than processing all the raw time series data. For example, an application could request daily summary data for a month, obtaining 30 records for an aspect (property) instead of ~2.5 million records of 1 second data for that same period.

Prerequisites

An asset (entity) is connected to MindSphere and produces time series data. The asset (entity) contains variables that have a numeric data type (e.g. Integer, Double).

Access

The following permissions are required for reading aggregated data:

  • Reading time series aggregates: iot.tsa.r

A user can only read data within his tenant and subtenants.

Basics

The IoT TS Aggregates Service automatically creates precalculated aggregates and stores them for later retrieval to enhance performance on aggregate queries. The following precalculated intervals are available.

  • 2 minute
  • 1 hour
  • 1 day

Intervals smaller than the smallest precalculated interval are also available and generated on the fly. When retrieving aggregate data, the client needs to specify the interval duration it is interested in. The following durations are supported.

  • 1-120 seconds
  • 1-60 minutes
  • 1-24 hours
  • 1+ days
  • 1+ weeks
  • 1+ months

For best performance, the aggregation interval should be an exact multiple of a precalculated aggregation interval, such as 10 minutes, 2 hours, 5 days, 3 weeks, or 2 months. The service also supports other requested aggregation intervals and will use raw time series and precalculated aggregations to calculate results where needed. For example, an application could ask for 30 second intervals or 15 minute intervals. These requests will take longer to process.

The interval durations available have some overlap that provides flexibility to the application. For example, 1 hour and 60 minutes represent the same time period, but allow different behavior. A 1-hour interval duration allows a user to request data from 5:00 – 10:00. A 60-minute interval duration can be used for that same time period, but can also be used for 5:30 – 10:30. The 1-hour duration would be rejected for 5:30 – 10:30 because the times don't align with hourly boundaries. Similarly, if the tenant is configured with the first day of the week being Monday, an interval duration of 1 week must start and end on a Monday. An interval duration of 7 days could start on any day of the week.

Each aggregated record contains an assortment summary of information,

  • including first value and time of first value of the interval
  • last value and time of last value of the interval
  • minimum value and time of the minimum value during the interval
  • maximum value and time of the maximum value during the interval
  • the count of the values during the interval
  • the sum of the values during the interval
  • and the average of the values during the interval.

The aggregated data is wall clock aligned based on the asset (entity) time zone

  • two-minute data will end at two minutes after the hour, four minutes after the hour, and so on.
  • hourly data will end at the top of the hour.
  • daily data will end at midnight in the entity time zone

Time zones that are 15 or 45 minutes off a UTC hour are not supported, such as Nepal standard time (UTC+05:45). Time zones that are 30 minutes off a UTC hour are supported, such as India (UTC+05:30). Time zones that are an even number of hours off of GMT are supported.

The data summarized in an aggregated interval is the data with time stamps greater than the start time of the interval and less than or equal to the end time of the interval. This ensures that count type of data is correctly reflected in the aggregated interval. For example, if a device provides a wall clock aligned count at the end of each five minutes, an hourly aggregation will include the data with time stamps from five minutes after the hour until the end of the hour (3:05 to 4:00 for example).

Aggregates are created based on arrival of data and time logic.

  • two-minute aggregated data is created within two minutes after the two-minute interval has finished.
  • hourly data is created within eight minutes after the end of the hour.
  • daily data is created within fifteen minutes after midnight in UTC time for this release.

Aggregated data is only created if time series data exists for that period. Aggregates are created based on the data that is available at the time. Late arriving data will not be included in the initial aggregated results, but will trigger a recalculation after a delay.

If a variable (property) is configured to contain quality code data, the service uses it to calculate the aggregates. The quality code is compared to the good and uncertain thresholds defined on the tenant (per default the values are set according to the OPC UA standard). Good data is defined as being anything less than or equal to the goodThreshold value. Uncertain data is defined as being anything greater than the goodThreshold value and less than or equal to the uncertainThreshold value. Bad data is defined as anything greater than the uncertainThreshold. Good and uncertain data is used to calculate the summary values listed above. Bad data is ignored for these calculations. Each aggregated record contains counts of the three types of data, countgood, countuncertain, and countbad. If no quality code data is present on a time series record, it is considered good.

Features

The IoT TS Aggregates Service exposes its API for realizing the following tasks:

  • Read aggregated interval data.
  • Specify the time range.
  • Specify the interval duration.
  • Select only the summary information you're interested in

Restrictions

To get the current list of restrictions go to release notes and choose the latest date. From there goto "MindAccess Developer Plan Subscribers and MindAccess Operator Plan Subscribers" and pick the IoT service you are interested in.

Example Scenario

A windmill produces time series data for the speed of the wind wheel. The speed of the wind wheel changes only every hour.

The IoT TS Aggregates Service API allows you to collect just the accumulated time series of one hour.

Requirements

  • The windmill is connected to MindSphere and produces time series data

API Specification

Download OpenAPI Specification

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.