Operations/Metrics

TimeSeries API offers a set of operations that can be run on the timeseries data. This document provides all the endpoints for different operations as well as examples of how to use the operations. The operations can be categorized in different groups depending on their functionality. There are 4 different categories of operations that we will discuss in this document:

Aggregate operations

Arithmetic operations

Logical operations

Round, filter And Absolute operations

Cleanse and Shift operations

HoldLastValue and Resample operations

Frequencies supported for Batch Processing:

  • “PT15M”, “PT1H”, “PT24H”

The endpoint for all the operations is the same:
POST /operations

The payload is an operation object providing all the parameters and information about the desired operation as well as the data required by that operation.

All the operations supported are described in detail in the following section.

Average

Request Body

[
    {
        "metric": "DailyAverage",
        "operations": [
          {
                "operation": "Aggregate",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"DailyAverage" } ],
                "parameters": { "function": "Average", "interval": "Daily"  }
          }
        ],
        "processingType": "stream"
    }
]

The API supports calculating average aggregate of the timeseries data on periods of QuarterHourly, HalfHourly , Hourly and Daily.
HalfHourly aggregates will be on the top of the hour and half past the hour.

Operation

Aggregate

Parameters

Key Values
function “Average”
Interval “QuarterHourly”, “HalfHourly”, “Hourly”, “Daily”

Processing Type

  • Stream
  • Batch

WeightedAverage

Request Body

[
    {
        "metric": "QuarterHourlyWeightedAverage",
        "operations": [ 
          {
                "operation": "Aggregate",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"QuarterHourlyWeightedAverage" } ],
                "parameters": { "function": "WeightedAverage", "interval": "QuarterHourly"  }
          }
        ],
        "processingType": "Batch",
        "frequency":"PT15M"
    }
]

The API supports calculating the weighted average aggregate of the timeseries data on a QuarterHourly period.

Operation

Aggregate

Parameters

Key Values
function “WeightedAverage”
Interval “QuarterHourly”

Processing Type

  • Stream
  • Batch

Sum

Request Body

[
    {
        "metric": "DailySum",
        "operations": [ 
          {
                "operation": "Aggregate",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"DailySum" } ],
                "parameters": { "function": "Sum", "interval": "Daily"  }
          }
        ],
        "processingType": "stream"
    }
]

The API supports calculating the sum of the timeseries data on periods of QuarterHourly, Hourly, and Daily.

Operation

Aggregate

Parameters

Key Values
function “Sum”
Interval “QuarterHourly”, “HalfHourly”, “Hourly”, “Daily”

Processing Type

  • Stream
  • Batch

Count

Request Body

[
    {
        "metric": "DailyCount",
        "operations": [ 
          {
                "operation": "Aggregate",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"DailyCount" } ],
                "parameters": { "function": "Count", "interval": "Daily"  }
          }
        ],
        "processingType": "stream"
    }
]

The API supports calculating the count of the timeseries data on periods of QuarterHourly, Hourly, and Daily.

Operation

Aggregate

Parameters

Key Values
function “Count”
Interval “QuarterHourly”, “HalfHourly”, “Hourly”, “Daily”

Processing Type

  • Stream
  • Batch

First

Request Body

[
    {
        "metric": "First",
        "operations": [ 
          {
                "operation": "Aggregate",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"First" } ],
                "parameters": { "function": "First", "interval": "QuarterHourly"  }
          }
        ],
        "processingType": "stream"
    }
]

The API allows to get the first sample of the timeseries data in QuarterHourly, HalfHourly, Hourly, Daily windows.

Operation

Aggregate

Parameters

Key Values
function “First”
Interval “QuarterHourly”, “HalfHourly”, “Hourly”, “Daily”

Processing Type

  • Stream
  • Batch

Last

Request Body

[
    {
        "metric": "Last",
        "operations": [ 
          {
                "operation": "Aggregate",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Last" } ],
                "parameters": { "function": "Last", "interval": "QuarterHourly"  }
          }
        ],
        "processingType": "stream"
    }
]

The API allows to get the Last sample of the timeseries data in QuarterHourly, HalfHourly, Hourly, Daily windows.

Operation

Aggregate

Parameters

Key Values
function “Last”
Interval “QuarterHourly”, “HalfHourly”, “Hourly”, “Daily”

Processing Type

  • Stream
  • Batch

Arithmetic Scalar

Request Body

[
    {
        "metric": "Add",
        "operations": [ 
          {
                "operation": "Add",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Add" } ],
                "parameters": { "scalar": 2.0  }
          }
        ],
        "processingType": "stream"
    }
]

All four arithmetic operations are supported for timeseries data. This operation does the arithmetic with respect to a scalar and returns the modified timeseries data.

Operation

Add, Sub, Mul, Div

Parameters

Key Values
scalar float

Processing Type

  • Stream
  • Batch

Arithmetic Vector

Request Body

[
    {
        "metric": "Add",
        "operations": [ 
          {
                "operation": "Add",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" }, {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Add" } ],
                "parameters": {}
          }
        ],
        "processingType": "stream"
    }
]

All four arithmetic operations are supported for timeseries data. This operation does the arithmetic with respect to the secondary vector of data and returns the result.

Operation

Add, Sub, Mul, Div

Parameters

{} (Empty)

Processing Type

  • Stream
  • Batch

Logical Scalar

Request Body

[
    {
        "metric": "Lt",
        "operations": [ 
          {
                "operation": "Lt",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Lt" } ],
                "parameters": { "scalar": 70.0  }
          }
        ],
        "processingType": "stream"
    }
]

Timeseries data can be compared to a scalar with the logical operators. The logical comparison will be applied to all the samples and the result will be returned as a 0 (False) and 1 (True).
The supported logical operators with a scalar are as follows:

  • Equal (Eq)
  • Not equal (NE)
  • Less than (lt)
  • Less than or equal (Lte)
  • Greater than (Gt)
  • Greater than or equal (Gte)

The logical comparison is applied to all the samples and the result is returned as a 0 (False) and 1 (True).

Eq, Ne, Lte, Lt, Gt, Gte

Parameters

Key Values
scalar float

Processing Type

  • Stream
  • Batch

Logical Vector

Request Body

[
    {
        "metric": "Lt",
        "operations": [ 
          {
                "operation": "Lt",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" }, {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Lt" } ],
                "parameters": {}
          }
        ],
        "processingType": "stream"
    }
]

Timeseries data can be compared to another timeseries with the logical comparison operators. The logical comparison will be applied to all the samples and the result will be returned as a 0 (False) and 1 (True).
The supported logical operators with a scalar are as follows:

  • Equal (Eq)
  • Not equal (NE)
  • Less than (lt)
  • Less than or equal (Lte)
  • Greater than (Gt)
  • Greater than or equal (Gte)

Operation

Eq, Ne, Lte, Lt, Gt, Gte

Parameters

{} (Empty)

Processing Type

  • Stream
  • Batch

Not

Request Body

[
    {
        "metric": "Not",
        "operations": [ 
          {
                "operation": "Not",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Not" } ],
                "parameters": {}
          }
        ],
        "processingType": "stream"
    }
]

This operation can be applied to binary data to calculate the logical complement of the values. The logical complement will be applied to all the samples and the result will be returned as a 0 (False) and 1 (True).

Operation

Not

Parameters

{} (Empty)

Processing Type

  • Stream
  • Batch

And/Or

Request Body

[
    {
        "metric": "And",
        "operations": [ 
          {
                "operation": "And",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"And" } ],
                "parameters": {}
          }
        ],
        "processingType": "stream"
    }
]

And and Or are the logical operations that can be applied to binary data on two timeseries. The logical complement will be applied to all the samples and the result will be returned as a 0 (False) and 1 (True).

Operation

And, Or

Parameters

{} (Empty)

Processing Type

  • Stream
  • Batch

Mask

Request Body

[
    {
        "metric": "Mask",
        "operations": [ 
          {
                "operation": "Mask",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Mask" } ],
                "parameters": {
                          "valuerangelist": [
                                            {"lower":-99999999, "upper":-500},
                                            {"lower":1000, "upper": 99999999}
                                            ],
                          "timerangelist": [
                                          {"starttime":"2016-06-01T06:00:00-05:00", "endtime":"2016-06-01T07:00:00-05:00"}
                                          ]
                }
          }
        ],
        "processingType": "stream"
    }
]

This operation is used to mask (remove) unwanted range of values from samples. Multiple ranges can be supplied. All the values that fall in that ranges will be removed. Samples can also be masked based on time ranges. All the samples falling in that date time period will be removed.

Operation

Mask

Parameters

Key Values
valuerangelist [{“lower”:float, “upper”: float },{“lower”: float, “upper”: float }]
timerangelist [{“starttime”: datetime, “endtime”: datetime}]

Processing Type

  • Stream
  • Batch

Where

Request Body

[
    {
        "metric": "Where",
        "operations": [ 
          {
                "operation": "Where",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Where" } ],
                "parameters": {
                          "valuerangelist": [
                                            {"lower":-99999999, "upper":-500},
                                            {"lower":1000, "upper": 99999999}
                                            ],
                          "timerangelist": [
                                          {"starttime":"2016-06-01T06:00:00-05:00", "endtime":"2016-06-01T07:00:00-05:00"}
                                          ]
                }
          }
        ],
        "processingType": "stream"
    }
]

This operation selects only samples from a range of values and a period of time. Multiple ranges can be supplied. All the values that fall in the ranges are returned. You can also select samples based on time ranges. All the samples falling in that date time period are returned.

Operation

Where

Parameters

Key Values
valuerangelist [{“lower”:float, “upper”: float },{“lower”: float, “upper”: float }]
timerangelist [{“starttime”: datetime, “endtime”: datetime}]

Processing Type

  • Stream
  • Batch

Round

Request Body

[
    {
        "metric": "Round",
        "operations": [ 
          {
                "operation": "Round",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Round" } ],
                "parameters": {"roundtodigits":3}
          }
        ],
        "processingType": "stream"
    }
]

This operation is used to round the values to a specific number of points after the point. Floating numbers are rounded to the nearest value.

Operation

Round

Parameters

Key Values
roundtodigits int

Processing Type

  • Stream
  • Batch

Absolute

Request Body

[
    {
        "metric": "Absolute",
        "operations": [ 
          {
                "operation": "Abs",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Absolute" } ],
                "parameters": {}
          }
        ],
        "processingType": "stream"
    }
]

This operation is used to get the absolute value.

Operation

Abs

Parameters

{} (Empty)

Processing Type

  • Stream
  • Batch

Cleanse

Request Body

[
    {
        "metric": "BoundsLimitCleanse",
        "operations": [ 
          {
                "operation": "Cleanse",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"BoundsLimitCleanse" } ],
                "parameters": {"function":"BoundsLimitCleanse","lowerbound": 140, "upperbound": 150}
          }
        ],
        "processingType": "stream"
    }
]

This operation is used to either trim samples to be within the specified range or return samples that are outside of the range (anomalies).

Operation

Cleanse

Parameters

Key Values
function “BoundsLimitCleanse”, “BoundsLimitAnomaly”
lowerbound int
upperbound int

Processing Type

  • Stream
  • Batch

Shift

Request Body

[
    {
        "metric": "ShiftByWindow",
        "operations": [ 
          {
                "operation": "Shift",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"ShiftByWindow" } ],
                "parameters": { "function":"ShiftByWindow","shift" : 2.0,  "direction": "forward"}
          }
          ],
        "processingType": "stream"
    }
]

This operation is used to shift sample time stamps forward or back based on window / time interval. Time interval is specified in ISO 8601 notation (PnDTnHnMnS format , eg. P10DT3H10M5S)

Operation

Shift

Parameters

Key Values
function “ShiftByWindow”, “ShiftByTime”
shift int, string
direction “forward”, “backward”

Processing Type

  • Stream
  • Batch

HoldLastValue

Request Body

[
    {
        "metric": "HoldLastValue",
        "operations": [ 
          {
                "operation": "HoldLastValue",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"HoldLastValue" } ],
                "parameters": {"function":"HoldLastValue", "interval": "QuarterHourly"}
          }
        ],
        "processingType": "stream"
    }
]

This operation helps to persist COV at set intervals (QuarterHourly, HalfHourly, Hourly)

Operation

HoldLastValue

Parameters

Key Values
function “HoldLastValue”
interval “QuarterHourly”, “HalfHourly”, “Hourly”

Processing Type

  • Stream
  • Batch

Resample

Request Body

[
    {
        "metric": "Resample",
        "operations": [ 
          {
                "operation": "HoldLastValue",
                "input": [ {"timeseriesId":"{{timeseries_id}}", "metric":"Raw" } ],
                "output": [ { "timeseriesId":"{{timeseries_id}}", "metric":"Resample" } ],
                "parameters": {"function":"Resample",   "frequency": "PT1M",}
          }
          ],
        "processingType": "stream"
    }
]

This operation helps to resample data to the required frequency (Minutes or Hours specified in ISO 8601 notation . For example, “PT1M” indicates 1 minute frequency)

Operation

Resample

Parameters

Key Values
function “Resample”
frequency string

Processing Type

  • Stream
  • Batch