Time Series Data Model
A time series uses tags, which are often used to represent sensors (for example, a temperature sensor).
Data Ingestion
Time series data sets are based on the idea of tags, which represent different types of values measured by sensors (for example, temperature or pressure). A data record consists of one Tag Name (Sensor type), and multiple datapoints, each comprised of a Timestamp (Time) and a Measurement (Value). As additional options, each datapoint can also contain the quality of its data, and the overall record can contain multiple attributes (key/value pairs) describing the asset.
| Term | Definition |
|---|---|
| Tag name |
(Required) Name of the tag (for example, "Temperature"). This does not need to be a unique value, and typically numerous sensors representing the same tag type will share this same tag name. Do not use the tag name to store attributes; you should instead store attributes like the sensor ID in the Attributes section. The tag name can contain alphanumeric characters, periods (.), slashes (/), dashes (-), underscores (_) and spaces and is limited to a maximum 256 characters. |
| Timestamp |
(Required) The date and time in UNIX epoch time, with millisecond precision. |
| Measurement | (Required) The value produced from your sensor. See Data Types for more information on what is accepted. Do not include the unit of measurement in the field, for example, |
| Qualities | (Optional) Quality of the data, represented by the values 0, 1, 2, 3. See Data Quality below for an explanation of data quality values. |
| Attribute | (Optional) Attributes are key/value pairs used to store data associated with a tag (for example: "ManufacturerGE":"AircraftID230"). This is useful for filtering data. Note: Attributes allow you to store additional relevant details about that specific data point—they should not be used to store large amounts of data. Do not use null values. |
| BackFill | (Optional) BackFill is a boolean flag that can be used to indicate whether this ingestion request includes backFill or non-live data. Data ingested with this option enabled will not be available to query immediately, but will be available eventually. Example: backFill: true Note: "backFill" field is a boolean and setting it to any other data type would return 400 (Bad Request). |
Data Quality
You can tag data with values that represent data quality, which enables you to query by quality in cases where you want to retrieve or process only data of a specific level of quality. Using data quality can help to ensure that the data you get back in the query result is the most relevant for your purpose.
| Value | Description |
|---|---|
| 0 | Bad quality. |
| 1 | Uncertain quality. |
| 2 | Not applicable. |
| 3 | Good quality. If you do not specify quality, the default is good (3). |
Data Types
The Time Series ingestion service accepts mixed data types.
The following table shows sample input and output for mixed variable types (text, number, and null). When designing your data model:- Do not use attributes as tag names. Keep the tag name as the type of data produced by the sensor (for example, "Temperature" or "Pressure"), and use attributes to distinguish between distinct sensors.
- Do not use timestamps as measurement values in your application.
| Ingestion JSON Input | Ingestion JSON Input Type | Query Output | Datapoint Type |
|---|---|---|---|
| 27 | long | 27 | number |
| "34" | string (max 256 characters) | 34 | number |
| 3.345 | float | 3.345 | number |
| "1.123" | string (max 256 characters) | 1.123 | number |
| "1.0E-2" | string (256 characters) | 0.01 | number |
| "abc" | string (max 256 characters) | "abc" | text |
| "true" | string (max 256 characters) | "true" | text |
| true / false | boolean | "true" / "false" | text |
| "null" | string (max 256 characters) | "null" | text |
| null | null | null | Null |
| "" | string (max 256 characters) | "" | null |
| " " | string (max 256 characters) | " " | null |
Data Consumption
- Query time series data specifying tags (sensors, etc) and a time window.
- Filter by attribute values.
- Retrieve all tags and attribute keys from the time series database.
- Add aggregates and interpolate data points in a given time window.
- Query the time series database for the latest values.Note: When you use the GET latest API, the query returns the latest data point.
- Delete tags and all the associated data points.
For more information about these APIs, see the API Documentation.