const aggregates = await client.timeseries.aggregate({ filter: { isString: true } });
console.log('Number of string timeseries: ', aggregates[0].count){
"items": [
{
"count": 123
}
]
}Aggregate time series
Required capabilities:
timeSeriesAcl:READ
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.
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.
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.
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.
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).
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.
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 |
const aggregates = await client.timeseries.aggregate({ filter: { isString: true } });
console.log('Number of string timeseries: ', aggregates[0].count){
"items": [
{
"count": 123
}
]
}Authorizations
Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
Body
Aggregates the time series that match the given criteria.
- Count
- CardinalityValues
- CardinalityProperties
- UniqueValues
- UniqueProperties
A query that matches items matching boolean combinations of other queries.
It is built by nesting one or more Boolean clauses, each of which is one of and, or, and not.
Each such clause contains one or more child clauses (though not can only have one).
Each child clause can be either another Boolean clause or a leaf filter.
- and
- or
- not
- equals
- in
- range
- prefix
- exists
- containsAny
- containsAll
- search
Show child attributes
Show child attributes
{
"or": [
{
"not": {
"and": [
{
"equals": {
"property": ["metadata", "manufacturer"],
"value": "acme"
}
},
{
"in": {
"property": ["name"],
"values": ["pump-1-temperature", "motor-9-temperature"]
}
},
{
"range": {
"property": ["dataSetId"],
"gte": 1,
"lt": 10
}
}
]
}
},
{
"and": [
{
"equals": { "property": ["assetId"], "value": 1234 }
},
{
"equals": {
"property": ["description"],
"value": "Temperature in Celsius"
}
}
]
}
]
}Show child attributes
Show child attributes
A query that matches items matching boolean combinations of other queries.
It's built by nesting one or more Boolean clauses, each of which is one of and, or, and not.
Each such clause contains one or more child clauses (though not can only have one).
Each child clause can be either another Boolean clause or a leaf filter.
- and
- or
- not
- in
- range
- prefix
Show child attributes
Show child attributes
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.
count Response
Response with the aggregated time series. The type of the response depends on the value of the aggregate parameter in the request.
- Count
- CardinalityValues
- CardinalityProperties
- UniqueValues
- UniqueProperties
1 elementShow child attributes
Show child attributes
Was this page helpful?