Api Key Authorization

As mentioned before, all the properties with retention policy historical are automatically stored in the system's time-series database. The property values can be queried anytime by POSTing a query object to property's data endpoint as shown above.

Query Object

You must specify either startAbsolute or startRelative but not both. Similarly, you may specify either endAbsolute or endRelative but not both. If either end time is not specified the current date and time is assumed.

Understanding Query Elements

Tags

It is possible to filter the data returned by specifying a tag. The data returned will only contain data points associated with the specified tag.

As of version 3, only the system designated tags are stored in the time-series database and can be used for filtering. User defined tags cannot be used.

The following table explains the system designated tags and their purpose:

Grouping

The results of the query can be grouped together.There are three ways to group the data; by tags, by a time range, and by value.

Grouping by Time

The time grouper groups results by time ranges. Possible unit values are “milliseconds”, “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”, and “years”.

For example, you could group data by day of week. Note that the grouper calculates ranges based on the start time of the query. So if you wanted to group by day of week and wanted the first group to be Sunday, then you need to set the query’s start time to be on Sunday.

"groupBy": [
      {
        "name": "time",
        "groupCount": "7",
        "rangeSize": {
          "value": "1",
          "unit": "days"
        }
      }
]

Grouping by Value

The value grouper groups by data point values. Values are placed into groups based on a range size. For example, if the range size is 100, then values between 0-99 are placed in the first group, values between 100-199 into the second group, and so forth.

This example groups value by a range size of 100.

"groupBy": [
      {
        "name": "value",
        "rangeSize": 100
      }
]

Grouping by Bin

The bin grouper groups data point values into bins or buckets. Values are placed into groups based on a list of bin values. For example, if the list of bins is 10, 20, 30, then values less than 10 are placed in the first group, values between 10-19 into the second group, and so forth.

This example groups values into groups of 2.

"groupBy": [
      {
        "name": "bin",
        "bins": ["2", "4", "6", "8"]
      }
]

🚧

Rule

value and bin grouping can be only applied to numeric data points.

Aggregators

Optionally you can specify aggregators. Aggregators perform an operation on data points and down samples. For example, you could sum all data points that exist in 5 minute periods.

Aggregators can be combined together. For example, you could sum all data points in 5 minute periods then average them for a week period.

Aggregators are processed in the order they are specified in the query object. The output of one is send to the input of the next.

Most aggregators support downsampling. Downsampling allows you to reduce the sampling rate of the data points and aggregate these values over a longer period of time. For example, you could average all daily values over the last week. Rather than getting 7 values you would get one value which is the average for the week. Sampling is specified with a “value” and a “unit”.

Supported aggregators

Connio time-series database supports various number of aggregators.

Aggregator Parameters

Range aggregator type

"aggregators": [
{
  "name": "sum",
  "alignSampling": true,
  "alignStartTime": true,
  "sampling": {
    "value": 1,
    "unit": "minutes"
  }
}]

Unit type

Unit is a time unit represented as a string and must be one of ( MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, YEARS)

Sampling type

A sampling is a json object containing two values a value and a unit. The value is a long and the unit is see unit.

📘

Sample Size

Sample size is not the same as the result set size. It represents the number of items processed in order to generate the query result. It can be equal or greater than the result set size.

👍

Time-Series Databases

Connio's historical data API is modelled after the open source project KairosDB. Some section of this document is directly adapted from this project. We highly suggest you to take a look at the KairosDB documentation to better understand the principles behind time-series databases.