Timeseries Functions

Limited access API

Limited access

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

Timeseries Functions

The goal of Custom Timeseries Functions is to enhance default functions (see Common Platform Functions) with custom functions written in javascript code. These functions will be managed with a Catalog defined for each organization.

Common Platform Functions

There will be a common catalog for all organizations with default platform Timeseries Functions. Defined functions are:

  • FIRST: the engine will store only the first received value per time bucket. The collection engine ignores the following values obtained in the same time bucket.
  • LAST: the engine will store only the last received value per time bucket, overwriting the previous ones.
  • AVG: the engine will calculate the arithmetic average of all received values in the configured time bucket. Only available in numeric values.
  • MAX: the engine will save the maximum value of all received values in the configured time bucket. Only available for numeric values.
  • MIN: the engine will save the minimum value of all received values in the configured time bucket. Only available for numeric values.
  • SUM: the engine will save the sum of all received values in the configured time bucket. Only available for numeric values.
  • COUNT: the engine will store the count of total number values received per time bucket.
  • MEDIAN: the engine will calculate the median of all received values in the configured time bucket. Only available in numeric values.
  • GEO_AVG: the engine will calculate the geometric average of all received values in the configured time bucket. Only available in numeric values.
  • VARIANCE: the engine will calculate the variance of all received values in the configured time bucket. Only available in numeric values.
  • STD_DEVIATION: the engine will calculate the standard deviation of all received values in the configured time bucket. Only available in numeric values.
Note

These functions will be available for querying with the API defined below. But it will not be possible to modify or delete them.

Custom Catalog

Each organization will have available Custom Timeseries Functions catalog for managing its functions. These functions will be available for defining Timeseries columns referencing them in aggregationFunction field. For example:

{
  "name": "basic_timeserie",
  "organizationId": "organizationName",
  "description": "time series description",
  "timeBucket": 86400,
  "retention": 2592000,
  "origin": "2021-01-01T00:00:00.000Z",
  "bucketColumn": "bucket_id",
  "identifierColumn": "Admin Identifier",
  "context": [
    ...
  ],
  "columns" [
      {
          "path":"some.path.A.value._current.value",
          "name":"columnaA",
          ...
          ...
          "aggregationFunction":"AVG", //platform aggregation function
      },
      
      
      {
          "path":"some.path.B.value._current.value",
          "name":"columnaB",
          ...
          ...
          "aggregationFunction":"myCustomTimeserieFunction" //custom function
      }
  ]
}
Warning

Defined API allows to modify Custom Aggregation Function’s script. Script modification may imply changes in aggregated data mean. Previous chunks data will not change so there can be a inconsistencies between new aggregated data and old values.

Note

Defined API allows to delete Custom Aggregation Function, but only if it is no used in any Timeserie.

Custom Timeseries Function script

Considerations when developing Custom Aggregation Function:

  • These are code’s implicit input parameters:
    • receivedValues: array of new values to be used for final value calculation.
    • currentValue: column’s current value.
    • extra: json with column’s current extra vars used for value calculation.
  • The code should use implicit input values to calculate the final value and then build result object.
  • It will be possible to use helper functions defined in JS API.
  • The code must return a json with two specific properties:
    • executionResult: If execution finished correctly OK value must be returned. If not, error description must be specified.
    • value: calculated value
    • extra: json with extra vars updated
    • Response example for AVG aggregation function result: 
      {
  "executionResult": "OK",
  "value": 5, 
  "extra":{
    "sum": 10,
    "count": 2
  }
}
Note

For further information about how to implement Custom Aggregation Functions check JS API doc.

Functions values types.

To validate that a Timeserie Function can be assigned to a Timeserie column, there will be used valueTypes field. This field will be an array of strings that accepts following values:

  • integer
  • number
  • string
  • boolean
  • date-time

These types are the same types specified for Timeseries column type field. When assigning a timeserie function to specific column will be checked that timeserie function has in the array the type specified in the column.

Note

This field is not mandatory and when not defined by default it will be empty array.

If timeserie function has empty valueTypes, no validation will be done when assigning to a column.

Note

It will not be possible to update timeserie function and remove one of the valueTypes if the function is being used by some column whose type is the removed value. Except if all valueTypes are removed, in this case there will not be any problem.

CustomSpec