Calculated time series

The content in this section describe features that are currently in preview and that are not yet generally available. The features are subject to change, and we do not recommend that you use them in production systems.

Calculated time series is currently available in API v0.6.

In this example we will show how you can do on the fly calculations to get a time series that is a function, including multiple time series. This is useful if you want to analyze or visualize a delta between two pressures, the rate or other, more complex functions.

Query time functions are not supporting aggregating the result or applying the function on raw data, as this will in general be too expensive and will result in high latency. Functions that are supported is evaluating functions on the aggregates. That is we support (avg([id1]) + avg([id2])), but not avg([id1] + [id2]).

In addition to specifying raw time series in the query expression, we add the possibility of adding aliases for aggregate time-series. An alias will be a separate json object that specifies the time series id, the aggregate to get, and the granularity. This alias can then be referenced in the function expression.

We allow mixing aggregates with raw data, as in [id1] - [average_of_id1], to give a graph of the deviation from the mean. In a similar vein, we allow specifying the granularity for each leaf node in the expression, so we can write [average_by_minute] - [average_by_hour] to graph how the minute averages deviate from the hour average over time.

If you want to plot the difference between two time series you can call:

POST /api/0.6/projects/<project>/timeseries/dataquery
Host: api.cognitedata.com
1
2

Post body:

{
  "items": [
    {
      "function": "[127389341691737]-[6826834587953108]",
      "name": "delta_temperature",
      "start": "1541210091980",
      "end": "1542210091980"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10

Response:

{
  "data": {
    "items": [
      {
        "name": "delta_temperature",
        "datapoints": [
          {
            "timestamp": 1541210400000,
            "value": 11.110638649316405
          },
          {
            "timestamp": 1541214000000,
            "value": 11.15609912846137
          },
          ...{
            "timestamp": 1542210071187,
            "value": 9.200000000000001
          },
          {
            "timestamp": 1542210082068,
            "value": 9.200000000000001
          }
        ]
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Where the function describes the operation on time series IDs (127389341691737 and 6826834587953108), within the start and end time. Supported operations are the standard SQL operations described here.

If you want to specify more complex calculations you can define an alias, which allows for combination of multiple functions. As an example, we could calculate the deviation in temperature from the hourly average.

{
  "start": "1541210091980",
  "end": "1542210091980",
  "items": [
    {
      "function": "[insidetemp]-[avginsidetemp]",
      "name": "delta_temperature",
      "aliases": [
        {
          "aggregate": "avg",
          "alias": "avginsidetemp",
          "granularity": "1h",
          "id": 127389341691737
        },
        {
          "alias": "insidetemp",
          "id": 127389341691737
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Response:

{
  "data": {
    "items": [
      {
        "name": "delta_temperature",
        "datapoints": [
          {
            "timestamp": 1541210094784,
            "value": 0.06935443055555623
          },
          {
            "timestamp": 1541210100548,
            "value": 0.06935443055555623
          },
          ...{
            "timestamp": 1542201392465,
            "value": 0.3948487499999995
          },
          {
            "timestamp": 1542201396948,
            "value": 0.3948487499999995
          }
        ]
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

This could be further expanded as the user defines. Supported aggregate operations are average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step. The query parameter granularity must also be specified, and defines the individual periods to calculate over. Valid entries for the granularity parameter are: day/d, hour/h, minute/m, second/s, or a multiple of these indicated by a number as a prefix, e.g. 12hour.

Last Updated: 8/19/2019, 8:29:01 AM