IoT Time Series Service¶
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.
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 their tenant, subtenants and shared assets.
Ingesting Time Series Data from a Field Device¶
An onboarded asset must be connected to MindSphere and produce 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.
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
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
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 will not 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.
The IoT Time Series Service exposes its API for realizing the following tasks:
- Read time series data for an asset or aspect
- Read time series data for a specified time range
- Read the latest uploaded data
- Create time series data for a single or multiple aspects
- Overwrite existing time series data
- Delete time series data for a single aspect of an asset within a given time range
Usage Quota and Limits¶
The Iot Time Series DELETE endpoint is restricted by the following limitations:
- Time Series data can only be deleted 7 days after it was submitted.
- The range of a delete request must be UTC hourly aligned.
- The range of a delete request cannot be greater than 7 day.
- The maximum number of delete requests per tenant is 1 per day.
- The maximum payload size for data upload is 1 MB.
- The Data Ingest rate throttling limit is 100 KB/s for Asset/Aspect combination in PUT Timeseries API.
- Double can have up to 38 digits of precision,and can be positive, negative, or zero.
- Positive range for Double : 1E-130 to 9.9999999999999999999999999999999999999E+125
- Negative range for Double : -9.9999999999999999999999999999999999999E+125 to -1E-130
- Requests are processed in order of arrival. Thus, the latest stored record might not reflect the latest request.
- Storage of empty strings is not supported. The respective fields are ignored.
- Queries with the URL parameter
latestValueare not available for String and Timestamp variables.
- Queries with the URL parameter
latestValuedo not consider records ingested more than 1 month or less than 2 hours ago.
- Queries without specified timestamps do not consider records older than 12 months.
- The maximum number of aspects (one or multiple assets) per data upload request is 5, with a maximum payload size of 100 KB and 100 records.
- The '+' character used to include timezone in timestamp must be encoded to '%2B' in time range. For example, 2017-09-21T14:08:00%2B02:00 instead of 2017-09-21T14:08:00+02:00.
- Timeseries data will not be retrieved via GET endpoint of Timeseries services for Data Ingested via IoT TS Bulk Services for past 7 days.
For Timeseries Data ingestion of past 7 days, use either IoT Timeseries Services or IoT TS Bulk Services. If both the methods are used, data consistency will be compromised.
For region Europe 2:
- Bulk data import for "Simulation" assets is not supported.
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.
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?
Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.