Aggregate time series

The aggregation API allows you to compute aggregated results from a set of time series, such as getting the number of time series in a project or checking what assets the different time series in your project are associated with (along with the number of time series for each asset). By specifying filter and/or advancedFilter, the aggregation will take place only over those time series that match the filters. filter and advancedFilter behave the same way as in the list endpoint.

The default behavior, when the aggregate field is not specified the request body, is to return the number of time series that match the filters (if any), which is the same behavior as when the aggregate field is set to count.

The following requests will both return the total number of time series whose name begins with pump:

{
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

and

{
  "aggregate": "count",
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The response might be:

{"items": [{"count": 42}]}
Setting aggregate to uniqueValues and specifying a property in properties (this field is an array, but currently only supports one property) will return all unique values (up to a maximum of 1000) that are taken on by that property across all the time series that match the filters, as well as the number of time series that have each of those property values.

This example request finds all the unique asset ids that are referenced by the time series in your project whose name begins with pump:

{
  "aggregate": "uniqueValues",
  "properties": [{"property": ["assetId"]}],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The response might be the following, saying that 23 time series are associated with asset 18 and 107 time series are associated with asset 76:

{
  "items": [
    {"values": ["18"], "count": 23},
    {"values": ["76"], "count": 107}
  ]
}
Setting aggregate to cardinalityValues will instead return the approximate number of distinct values that are taken on by the given property among the matching time series.

Example request:

{
  "aggregate": "cardinalityValues",
  "properties": [{"property": ["assetId"]}],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result is likely exact when the set of unique values is small. In this example, there are likely two distinct asset ids among the matching time series:

{"items": [{"count": 2}]}
Setting aggregate to uniqueProperties will return the set of unique properties whose property path begins with path (which can currently only be ["metadata"]) that are contained in the time series that match the filters.

Example request:

{
  "aggregate": "uniqueProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result contains all the unique metadata keys in the time series whose name begins with pump, and the number of time series that contains each metadata key:

{
  "items": [
    {"values": [{"property": ["metadata", "tag"]}], "count": 43},
    {"values": [{"property": ["metadata", "installationDate"]}], "count": 97}
  ]
}
Setting aggregate to cardinalityProperties will instead return the approximate number of different property keys whose path begins with path (which can currently only be ["metadata"], meaning that this can only be used to count the approximate number of distinct metadata keys among the matching time series).

Example request:

{
  "aggregate": "cardinalityProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result is likely exact when the set of unique values is small. In this example, there are likely two distinct metadata keys among the matching time series:

{"items": [{"count": 2}]}

The aggregateFilter field may be specified if aggregate is set to cardinalityProperties or uniqueProperties. The structure of this field is similar to that of advancedFilter, except that the set of leaf filters is smaller (in, prefix, and range), and that none of the leaf filters specify a property. Unlike advancedFilter, which is applied before the aggregation (in order to restrict the set of time series that the aggregation operation should be applied to), aggregateFilter is applied after the initial aggregation has been performed, in order to restrict the set of results.

Click here for more details about aggregateFilter.

When aggregate is set to uniqueProperties, the result set contains a number of property paths, each with an associated count that shows how many time series contained that property (among those time series that matched the filter and advancedFilter, if they were specified) . If aggregateFilter is specified, it will restrict the property paths included in the output. Let us add an aggregateFilter to the uniqueProperties example from above:

{
  "aggregate": "uniqueProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}},
  "aggregateFilter": {"prefix": {"value": "t"}}
}

Now, the result only contains those metadata properties whose key begins with t (but it will be the same set of metadata properties that begin with t as in the original query without aggregateFilter, and the counts will be the same):

{
  "items": [
    {"values": [{"property": ["metadata", "tag"]}], "count": 43}
  ]
}

Similarly, adding aggregateFilter to cardinalityProperties will return the approximate number of properties whose property key matches aggregateFilter from those time series matching the filter and advancedFilter (or from all time series if neither filter nor aggregateFilter are specified):

{
  "aggregate": "cardinalityProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}},
  "aggregateFilter": {"prefix": {"value": "t"}}
}

As we saw above, only one property matches:

{"items": [{"count": 1}]}

Note that aggregateFilter is also accepted when aggregate is set to cardinalityValues or cardinalityProperties. For those aggregations, the effect of any aggregateFilter could also be achieved via a similar advancedFilter. However, aggregateFilter is not accepted when aggregate is omitted or set to count.

Rate and concurrency limits

Rate and concurrency limits apply this endpoint. If a request exceeds one of the limits, it will be throttled with a 429: Too Many Requests response. More on limit types and how to avoid being throttled is described here.

Limit Per project Per user (identity)
Rate 15 requests per second 10 requests per second
Concurrency 6 concurrent requests 4 concurrent requests
Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json

Aggregates the time series that match the given criteria.

One of:
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (TimeSeriesFilterLanguage)
object (Filter)
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (in (object) or range (object) or prefix (object))) (TimeSeriesAggregateFilter)
aggregate
string

The count aggregation gets the number of time series that match the filter(s). This is the default aggregation, which will also be applied if aggregate is not specified.

Value: "count"
Responses
200

Response with the aggregated time series. The type of the response depends on the value of the aggregate parameter in the request.

400

The response for a failed request.

post/timeseries/aggregate
Request samples
application/json
{
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "filter": {
    • "name": "string",
    • "unit": "string",
    • "unitExternalId": "string",
    • "unitQuantity": "string",
    • "isString": true,
    • "isStep": true,
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetIds": [
      ],
    • "externalIdPrefix": "my.known.prefix",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      }
    },
  • "aggregateFilter": {
    • "and": [
      ]
    },
  • "aggregate": "count"
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ]
}
➔ Next to Create time series