Skip to content

IoT Time Series Service

Idea

The IoT Time Series Service is used to create, read, update, and delete time series data. Time series data is stored against an asset and an aspect. A time series record consists of a timestamp, one or more values, and an optional quality indicator for each variable, which is defined by the aspect type. Within the IoT Time Series Service you can store and query time series data with a precision of 1 millisecond.

Access

Prerequisites

The prerequisites depend on the use case:

  • Ingesting time series data from a field device: An onboarded asset is connected to MindSphere and produces time series data. A valid mapping must exist from device data points to asset variables. For instructions refer to Uploading agent data.
  • Ingesting time series data from an application: An asset with respective variables must exist.

Roles and Scopes

For accessing this service you need to have the respective roles listed in IoT Time Series Service roles and scopes.

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

Basics

A time series record consists of a timestamp, one or more values, and an optional quality indicator for each value, as defined in the aspect type definition. If there are multiple variables in the aspect, they are expected to arrive in the same payload. Writing a time series record with the same timestamp, asset and aspect as an existing one completely overwrites the old record. There is no versioning of data.

The timestamp may be specified with millisecond precision. Measurement values must match the type that is defined in the aspect type. Time series data can be of type int, long, double, boolean, string, big_string (blobs), or timestamp. The maximum sizes of strings and big strings are defined in the aspect type, and can be up to 255 and 100,000 respectively. The maximum size of a time series record is 200,000 byte. Each data type is validated: longs, doubles, and timestamps using eight byte, integers using four byte, strings and big strings using two byte per character, and booleans using one byte.

In the aspect type definition, there is a qualitycode field, which indicates whether quality code data will accompany the time series data. If the qualitycode value is true for a variable (property), the name of the quality code property is the same as the variable (property) name, extended by a _qc suffix. For example, the quality code property for the variable temperature would be temperature_qc.

Multiple records for an asset and aspect can be written in one call to the service. Records can be read and deleted by identifying the asset, aspect, and time range.

When writing or deleting data, the default behavior of the service is to queue the incoming request and perform the physical writes to the underlying data store asynchronously. If a user writes time series data and immediately tries to read it back, it may not yet be present in the data store and it won't be returned. If a user deletes data and then reads that time range, the data may not have been physically deleted yet, and could be returned in the response. Requests for an asset are processed in the order they are received.

Features

The IoT Time Series Service exposes its API for realizing the following tasks:

  • Read time series data for a single asset and aspect
  • Read time series data for a specified time range
  • Read the latest value
  • Write or update time series data for a single asset and aspect
  • Overwrite existing time series data
  • Delete time series data for a single asset and aspect within a given time range

Limitations

  • The maximum size of a write payload to the Time Series PUT endpoint is 1 MB.
  • The maximum range for a double is -9.9999999999999999999999999999999999999E+125 to 9.9999999999999999999999999999999999999E+125.

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

Example Scenario

A wind turbine is connected to MindSphere. The blades move with a constantly changing speed. A sensor measures the speed and sends the data via MindConnect to MindSphere.

The IoT Time Series Service API allows you to write and read the speed data of the wind wheel.

Any questions left?

Ask the community


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