Stream summaries
- Last UpdatedAug 20, 2026
- 9 minute read
Stream Management offers summary statistics for individual streams over a user specified index interval. The available summaries are defined here. This topic provides an overview of time-based summary routes as well as updated definitions of all available summary statistics.
Time based summaries
Stream Management supports time-based summaries for individual streams. Time-based summaries allow the user to group intervals into convenient calendar-based time units such as minutes, hours, days, months and years. Time-based summaries are only available for streams having a single DateTime or DateTimeOffset index. The time-based summaries are available from the following endpoints:
-
/Streams/{streamId}/Data/Time/Summaries
-
/Streams/{streamId}/Data/Transform/Time/Summaries
These routes support the following query parameters:
|
Parameter |
Description |
Required? |
|---|---|---|
|
startTime |
ISO 8601 Date and Time (TZ format) |
Yes |
|
endTime |
ISO 8601 Date and Time (TZ format) |
Yes |
|
timeUnit |
Minute, Hour, Day, Month, Year |
Yes |
|
timeZone |
String |
No (UTC default) |
|
startBoundaryType |
String or integer |
No (if specified must also specify endBoundaryType) |
|
endBoundaryType |
String or integer |
No (if specified must also specify startBoundaryType |
|
emptyIntervalMode |
String or integer |
No (NaN default) |
startBoundaryType and endBoundaryType can only be used in the following combinations:
-
startBoundaryType=SdsBoundaryType.Exact and endBoundaryType=SdsBoundaryType.Inside
-
startBoundaryType=SdsBoundaryType.Inside and endBoundaryType=SdsBoundaryType.Exact
A list of supported timeZone IDs is available in the Microsoft document Default Time Zones.
emptyIntervalMode can have the following values (for time based summaries):
-
NaN (default) Summary statistics for intervals with no data will be returned with NaN values for all statistics except count which will be zero.
-
Zero Summary statistics for intervals with no data will be returned with 0 values for all statistics.
Example time-based summaries requests and responses
The following examples show typical requests and responses for time-based summaries with different index types.
DateTime
For data with an SdsType with the following properties:
{
"id": "SdsExampleType",
"properties": [
{
"name": "Timestamp",
"sdsTypeCode": "DateTime"
},
{
"id": "Quality",
"sdsTypeCode": "Int32"
},
{
"id": "Value",
"sdsTypeCode": "Double"
}
]
}
Request: streams/{streamId}/Data/Time/Summaries?startTime=2025-01-01T08:00:00Z&endTime=2026-01-01T08:00:00Z&timeUnit=year&timeZone=Pacific Standard Time
Response:
{
"items": [
{
"label": 2025,
"timeZone": "Pacific Standard Time",
"start": {
"timestamp": "2025-01-01T08:00:00Z"
},
"end": {
"timestamp": "2026-01-01T08:00:00Z"
},
"summaries": {
"count": {
"timestamp": 12,
"quality": 12,
"value": 12
},
"minimum": {
"quality": 100,
"value": 12
},
"maximum": {
"quality": 1200,
"value": 901
},
"range": {
"quality": 1100,
"value": 889
},
"total": {
"quality": 7800,
"value": 5474
},
"mean": {
"quality": 650,
"value": 456.1666666666667
},
"standardDeviation": {
"quality": 360.5551275463989,
"value": 302.263230655104
},
"populationStandardDeviation": {
"quality": 345.2052529534663,
"value": 289.39501070720314
},
"weightedMean": {
"quality": 651.7964071856287,
"value": 475.4251497005988
},
"weightedStandardDeviation": {
"quality": 330.8617598114979,
"value": 183.29259143974397
},
"weightedPopulationStandardDeviation": {
"quality": 315.4643101922241,
"value": 174.7626288236728
}
}
}
]
}
DateTime empty interval response (emptyIntervalMode=NaN)
{
"items": [
{
"label": 2025,
"timeZone": "Pacific Standard Time",
"start": {
"timestamp": "2025-01-01T08:00:00Z"
},
"end": {
"timestamp": "2026-01-01T08:00:00Z"
},
"summaries": {
"count": {
"timestamp": 0,
"quality": 0,
"value": 0
},
"minimum": {
"quality": "NaN",
"value": "NaN"
},
"maximum": {
"quality": "NaN",
"value": "NaN"
},
"range": {
"quality": "NaN",
"value": "NaN"
},
"total": {
"quality": "NaN",
"value": "NaN"
},
"mean": {
"quality": "NaN",
"value": "NaN"
},
"standardDeviation": {
"quality": "NaN",
"value": "NaN"
},
"populationStandardDeviation": {
"quality": "NaN",
"value": "NaN"
},
"weightedMean": {
"quality": "NaN",
"value": "NaN"
},
"weightedStandardDeviation": {
"quality": "NaN",
"value": "NaN"
},
"weightedPopulationStandardDeviation": {
"quality": "NaN",
"value": "NaN"
}
}
}
]
}
DateTimeOffset
For data with an SdsType with the following properties:
{
"id": "SdsExampleType",
"properties": [
{
"name": "Timestamp",
"sdsTypeCode": "DateTimeOffset"
},
{
"id": "Quality",
"sdsTypeCode": "Int32"
},
{
"id": "Value",
"sdsTypeCode": "Double"
}
]
}
Request: streams/{streamId}/Data/Time/Summaries?startTime=2025-01-01T08:00:00Z&endTime=2026-01-01T08:00:00Z&timeUnit=year&timeZone=Pacific Standard Time
Response:
{
"items": [
{
"label": 2025,
"timeZone": "Pacific Standard Time",
"start": {
"timestamp": "2025-01-01T00:00:00-08:00"
},
"end": {
"timestamp": "2026-01-01T00:00:00-08:00"
},
"summaries": {
"count": {
"timestamp": 12,
"quality": 12,
"value": 12
},
"minimum": {
"quality": 100,
"value": 12
},
"maximum": {
"quality": 1200,
"value": 901
},
"range": {
"quality": 1100,
"value": 889
},
"total": {
"quality": 7800,
"value": 5474
},
"mean": {
"quality": 650,
"value": 456.1666666666667
},
"standardDeviation": {
"quality": 360.5551275463989,
"value": 302.263230655104
},
"populationStandardDeviation": {
"quality": 345.2052529534663,
"value": 289.39501070720314
},
"weightedMean": {
"quality": 651.7964071856287,
"value": 475.4251497005988
},
"weightedStandardDeviation": {
"quality": 330.8617598114979,
"value": 183.29259143974397
},
"weightedPopulationStandardDeviation": {
"quality": 315.4643101922241,
"value": 174.7626288236728
}
}
}
]
}
Response for a DateTimeOffset empty interval (emptyIntervalMode=NaN)
{
"items": [
{
"label": 2025,
"timeZone": "Pacific Standard Time",
"start": {
"timestamp": "2025-01-01T00:00:00-08:00"
},
"end": {
"timestamp": "2026-01-01T00:00:00-08:00"
},
"summaries": {
"count": {
"timestamp": 0,
"quality": 0,
"value": 0
},
"minimum": {
"quality": "NaN",
"value": "NaN"
},
"maximum": {
"quality": "NaN",
"value": "NaN"
},
"range": {
"quality": "NaN",
"value": "NaN"
},
"total": {
"quality": "NaN",
"value": "NaN"
},
"mean": {
"quality": "NaN",
"value": "NaN"
},
"standardDeviation": {
"quality": "NaN",
"value": "NaN"
},
"populationStandardDeviation": {
"quality": "NaN",
"value": "NaN"
},
"weightedMean": {
"quality": "NaN",
"value": "NaN"
},
"weightedStandardDeviation": {
"quality": "NaN",
"value": "NaN"
},
"weightedPopulationStandardDeviation": {
"quality": "NaN",
"value": "NaN"
}
}
}
]
}
Label definitions
The label value in each interval depends on the selected timeUnit, as shown below.
|
TimeUnit |
Label |
Name/Description |
|---|---|---|
|
Day |
0 |
Sunday |
|
1 |
Monday |
|
|
2 |
Tuesday |
|
|
3 |
Wednesday |
|
|
4 |
Thursday |
|
|
5 |
Friday |
|
|
6 |
Saturday |
|
|
Month |
1 |
January |
|
2 |
February |
|
|
3 |
March |
|
|
4 |
April |
|
|
5 |
May |
|
|
6 |
June |
|
|
7 |
July |
|
|
8 |
August |
|
|
9 |
September |
|
|
10 |
October |
|
|
11 |
November |
|
|
12 |
December |
|
|
Hour |
0 |
12am to 1am |
|
1 |
1am to 2am |
|
|
2 |
2am to 3am |
|
|
... |
... |
|
|
23 |
11pm to 12am |
Calculated summaries
When you send an API request to the List Summaries endpoint, the REST API responds with a list of calculated summaries for each interval queried in the request. Calculated summaries are different types of statistical measures of a data stream that can help you summarize, analyze, or interpret data. Only stored values are used for non-weighted properties, while interpolated values are used for weighted properties.
The following calculated summaries are included in the response body of your request to the List Summaries endpoint:
|
Summary |
Description |
|
|---|---|---|
|
Count |
The numerical tally of stored values within an interval. |
|
|
Minimum |
The smallest or lowest value observed within an interval. |
|
|
Maximum |
The largest or highest value observed within an interval. |
|
|
Range |
The difference between the maximum and minimum values within an interval. |
|
|
Total |
The sum of all stored data points within an interval |
|
|
Mean |
The average of the set of numerical values within an interval. |
|
|
StandardDeviation |
A measure of the dispersion or spread of data points within a sample dataset. It quantifies how much individual data points deviate from the mean (average) wihtin an interval. |
|
|
PopulationStandardDeviation |
A measure of the dispersion or spread of data points within a population. It quantifies how much individual data points deviate from the mean (average) of the entire population. |
|
|
WeightedMean |
A type of average that takes into account not only the values within an interval but also the index weights associated with each value. It is used when different data points have varying degrees of importance or significance. |
|
|
WeightedStandardDeviation |
A measure of the dispersion or spread of data points within a sample with an index weight applied that indicates relative significance to each value in a set of values. Values with a higher value for their index weight are considered more significant to a sample as compared to the other values in a sample. |
|
|
WeightedPopulationStandardDeviation |
A measure of the dispersion or spread of data points within a population, where each data point is assigned an index weight based on its importance or significance. This concept extends the traditional population standard deviation by incorporating index weights that reflect the relative importance of individual data points. |
|
Parameters
Use the following parameters when calling the List Summaries endpoint.
|
Parameter |
Description |
Required |
|---|---|---|
|
startIndex |
Start index |
Yes |
|
endIndex |
End index |
Yes |
|
count |
Number of intervals to be returned |
No (1 is default) |
|
filter |
Expression used to filter the result set based on property values |
No |
|
emptyIntervalMode |
How intervals with no data should be formatted in response |
No (NaN is default) |
|
interpolationModeOverride |
Interpolation mode override for calculating boundary values and weighted summary statistics. |
No |
|
extrapolationModeOverride |
Extrapolation mode override for calculating boundary values and weighted summary statistics. |
No |
Empty interval mode
emptyIntervalMode is a query parameter that can be specified during data summaries calls to determine how intervals with no data should be handled in the response.
emptyIntervalMode can have the following values:
-
NaN (default) Summary statistics for intervals with no data will be returned with NaN values for all statistics except count which will be zero.
-
Zero Summary statistics for intervals with no data will be returned with 0 values for all statistics.
-
BoundaryInterpolation Summary statistics for intervals with no stored data will be calculated using the interpolated / extrapolated boundary values.
Notes:
-
If standard deviation type statistics cannot be calculated (for example, the interval only has 0-1 data points) and would otherwise result in NaN, 0 will be returned instead for mode Zero. For NaN mode, NaN will be returned.
-
BoundaryInterpolation mode treats the interpolated boundaries as continuous, and not as discrete values. This means an interval summary will have the following results if both the start and end boundaries have non-null values:
Statistic
Value
Count
0
Min
Min(startValue, endValue)
Max
Max(startValue, endValue)
Range
Abs(startValue endValue)
Total
NaN
Mean
NaN
Standard Deviation
NaN
Population Standard Deviation
NaN
Weighted Mean
Avg(startValue, endValue)
Weighted Standard Deviation
NaN
Weighted Population Standard Deviation
0
Interpolation / extrapolation mode overrides
When interpolation and/or extrapolation mode override is specified, summary statistics for intervals with no data will be returned using the interpolated values at the interval boundaries. This will override the settings of the type/stream for calculating boundary values and summary statistics.
Weighted summaries
In Stream Management, index-weighted summary calculations are provided for type properties that support and have a non-discrete interpolation mode set. These calculations are performed using a continuous-domain (measure-weighted) representation of data using a piecewise-defined interpolant. This is illustrated in the following diagram (using continuous interpolation in this example) where weights and corresponding values are represented for the singular interval [A,D], where A and D are values on the interval boundaries and B and C are stored values within the interval:
Here, if BC = 2 * AB = 2 * CD, the weights can be simplified to w(AB) = 1, w(BC) = 2, and w(CD) = 1. Here we see that we have N 1 (3) weights as mentioned in the formulas above.
Interval boundary behavior
This section describes how interval boundaries are interpreted when summaries are calculated.
Inclusion/exclusion
The following rules define which boundary values are included in each interval.
-
The start boundary of every interval is exclusive with the exception of the first interval returned.
-
The end boundary of every interval returned is inclusive.
Interval start and end
Each interval contains a start and end data point. The data points that are used for start and end are determined in the following order:
1. If there is a stored data point that coincides with the interval boundary, that data point is used.
2. If there is a data point that can be interpolated at the interval boundary, that data point is used.
3. If there is a data point that can be extrapolated at the interval boundary, that data point is used.
4. If there are stored data points present in the interval, then the closest stored data point to the boundary is used.
5. If none of the above apply, then just the index of the interval boundary is returned without a corresponding value.