Limited access

This feature is only available to root and super_admin_domain profiles. Ask your administrator for proper user role profiling.

What a time series is

A time series turns the stream of values a device sends into a table of rows over time: one row per device per time period, with each column holding a value aggregated over that period.

Ask for the average temperature per hour of ten thousand devices for the last month. Over data points that is millions of raw values to fetch and aggregate yourself. Over a time series it is already computed — the engine aggregated each hour as the data arrived.

That is the trade: you declare up front what you want aggregated and how, and in exchange the query is cheap.

Time buckets

The aggregation period is called a time bucket, and two fields define it:

Field Meaning
origin The starting date of the time series
timeBucket The length of each period in seconds, counted from origin

With an origin of 2022-01-01T00:00:00.000Z and a one hour bucket, the first period runs from 2022-01-01T00:00:00.001Z to 2022-01-01T01:00:00.000Z, the second from 2022-01-01T01:00:00.001Z to 2022-01-01T02:00:00.000Z, and so on:

2022-01-01T00:00:00.000Z -> 2022-01-01T01:00:00.000Z -> 2022-01-01T02:00:00.000Z ->...

Setting timeBucket to 0 seconds switches the engine into a different mode, storing every value instead of aggregating:

  • With only context columns defined, one record is saved per event received, and only when a column value actually changed — so you get a change log over time.
  • With aggregated columns defined, data is grouped by the at field of the incoming data points, and the aggregation function is applied when a new event arrives with the same at.

Which store do I want?

Time series Data points Data sets
Holds Values aggregated per period Every raw value Latest values, flat table
Rows One per device per bucket One per measurement One per device
Aggregation Computed on ingestion You compute it None
Best for Trends and history at scale Auditing exact readings Exports and tabular views

The two halves of the API

Defining a time series is administration: you declare the columns, their aggregation functions, the bucket length and the retention. Done once, usually by an administrator.

Querying a time series is what applications do every day: POST a filter and read rows back, as JSON or CSV.

The aggregation functions available to columns come from the time series functions catalog, which also lets you register your own.

API specification