Time Series Functions

Limited access

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

Introduction

The objective of custom time series functions is to augment the capabilities of the default functions (see Common Platform Functions) through the addition of bespoke functions written in JavaScript. These functions will be managed through the creation of a catalogue tailored to the specific requirements of each organisation.

Common Platform Functions

A common catalogue will be established for all organisations, comprising default platform time series functions. The following functions have been defined:

  • FIRST: Please note that the engine will store only the first received value per time bucket. Consequently, the collection engine will ignore the following values obtained in the same time bucket.
  • LAST: Please note that the engine will store only the last received value per time bucket, overwriting the previous ones.
  • AVG: The engine will calculate the arithmetic mean of all values received within the specified time interval. This feature is only available for numeric values.
  • MAX: The engine will save the maximum value of all received values within the configured time frame. Please note that this feature is only available for numeric values.
  • MIN: The engine will save the lowest value of all received values within the configured time frame. This feature is only available for numeric values.
  • SUM: The engine will accumulate the total of all received values within the specified time interval. This feature is only available for numeric values.
  • COUNT: The engine will record the total number of values received in each time bucket for subsequent analysis.
  • MEDIAN: The engine will calculate the median of all received values within the configured time bucket. Please note that this feature is only available for numeric values.
  • GEO_AVG: The engine will calculate the geometric average of all received values within the configured time bucket. Please note that this feature is only available for numeric values.
  • VARIANCE: The engine will calculate the variance of all received values within the configured time bucket. Please note that this feature is only available for numeric values.
  • STD_DEVIATION: The engine will calculate the standard deviation of all received values within the configured time bucket. Please note that this feature is only available for numeric values.
Note

Please note that these functions will be available for querying with the API defined below. However, please be aware that it will not be possible to modify or delete them.

Custom Catalog

Each organisation will have access to a custom time series functions catalogue, which will enable them to manage their functions effectively. These functions can be used to define time series columns, which can then be referenced in the aggregationFunction field. The following example illustrates this process:

{
  "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

The defined API enables the modification of the script for the custom aggregation function. It should be noted that such modifications may result in changes to the aggregated data. Consequently, there is a possibility of inconsistencies between the new aggregated data and the previous values.

Note

The defined API permits the deletion of a custom aggregation function, provided that it is not utilised in any time series.

Custom Time series Function script

Considerations when developing Custom Aggregation Function:

The following are the code’s implicit input parameters:

  • receivedValues: an array of new values to be used for the final value calculation. The column’s current value is represented by the currentValue parameter.

    • extra: JSON file containing the current extra variables for the column, used for the value calculation. The code should utilise implicit input values to calculate the final value and subsequently construct the result object. It will be possible to use helper functions defined in the JS API. The code must return a JSON with two specific properties:

  • executionResult: If the execution was completed successfully, the OK value must be returned. If not, an error description must be provided.

  • value: The calculated value

  • extra: A JSON with the updated extra variables

    ```json
{
  "executionResult": "OK",
  "value": 5, 
  "extra":{
    "sum": 10,
    "count": 2
  }
}
```
Note

For further details on how to implement custom aggregation functions, please refer to the JavaScript API documentation, specifically the section on aggregation functions.

Functions values types

To confirm that a time series function can be assigned to a time series column, the valueTypes field will be used. This field is an array of strings that accepts the following values:

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

These types are the same as those specified for time series column type fields. When assigning a time series function to a specific column, the system will verify that the time series function in the array matches the type specified for that column.

Note

Please note that this field is not mandatory. If it is not defined by default, it will be set to an empty array. In the event that the time series function has empty valueTypes, no validation will be carried out when assigning to a column.

Note

Please note that it will not be possible to update the time series function and remove one of the ‘valueTypes’ if the function is being used by some column whose type is the removed value. However, if all valueTypes are removed, this should not cause any issues.

Comprehensive API actions

Existing Timeseries Functions List

Getting custom timeserie functions full catalog

In both instances, only the metadata will be retrieved (no script) from both the organisations’ custom timeseries functions and the platform timeseries functions.

API specification