Provides a way to query aggregated channel data for time-based channels. You can specify the number of measured values to be sent for a specific time range and select the minimum, maximum and average aggregations for equidistant signals and the edge count value and the initial raw value for non-equidistant signals.
By default, the API uses the architecture of ibaHD-Server, where each channel is stored in multiple aggregation levels to enable fast and efficient retrieval of data over longer periods of time. Possible use cases are client visualizations (e.g. a monthly overview) where the screen size limits the amount of data that can be displayed simultaneously, as well as the provision of pre-aggregated data for subsequent aggregations where min/max/average data can be used as a source.
The aggregation algorithm can be changed from the standard algorithm "Min/Max/Avg downsampling" to the alternative algorithm "Linear interpolation downsampling". This algorithm attempts to select raw data points at equidistant intervals (required time range / required measured value) and applies linear interpolation between neighboring measured values if the stored measured values do not exactly match the time stamps of the target values.
Note |
|
|---|---|
 |
Depending on the time range queried, the algorithm works on the next aggregation level or the raw data. The maximum, minimum and average values may not be accurate. If aggregated data is used, data that is not part of the period queried is sometimes included in the calculation of the values in the marginal areas. In order to keep the effort required to determine the exact data within reasonable limits for users, the data in the marginal areas is determined with the aid of a weighting function. When using raw data, ibaHD-Server cannot use the aggregation levels to speed up processing and is therefore more resource-intensive than the standard "Min/Max/Avg downsampling" algorithm. |
Message "GetAggregatedChannelDataRequest"
Structure
GetAggregatedChannelDataRequest{
}
Parameter
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
time_range_from |
int64 |
Start time of the requested time range in Unix time stamp format in microseconds |
|
2 |
time_range_to |
int64 |
End time of the requested time range in Unix time stamp format in microseconds |
|
3 |
channel_ids |
string |
Channel IDs in the same format as they were returned in the response list of GetHdStoreSchema(), see GetHdStoreSchema(). |
|
4 |
sample_count |
int64 |
Number of measured values that are returned. The value must be > 0. |
|
5 |
min_aggregation |
bool |
Selection of the aggregated values to be sent with the response |
|
6 |
max_aggregation |
bool |
|
|
7 |
avg_aggregation |
bool |
|
|
8 |
aggregation_algorithm_type |
enum (AggregationAlgorithmType) |
Algorithm for downsampling the data, Default value MIN_MAX_AVG_DOWNSAMPLING if no specification is made |
|
9 |
add_extra_sample_out_of_time_range |
bool |
If True, an additional measured value is requested before and after the desired time range. No additional values are added for digital channels, but the first value is before time_range_from. This option is only available for the MIN_MAX_AVG_DOWNSAMPLING algorithm. |
Message "GetAggregatedChannelDataResponse"
List of time stamps for the aggregated measured values, divided into the various channel formats.
Structure
GetAggregatedChannelDataResponse{
AggregatedChannel{
FloatValues{…}
DoubleValues{…}
StringValues{…}
DigitalValues{…}
}
}
Parameter
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
timestamps |
int64 |
Timestamp for the channels DATA_TYPE_FLOAT_VALUES and DATA_TYPE_DOUBLE_VALUES as Unix timestamp in microseconds |
|
2 |
aggregated_channels |
- |
Channels containing values for the selected aggregations (min, max, avg) One Message AggregatedChannel is returned per channel, see Message "AggregatedChannel". |
Message "AggregatedChannel"
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
channel_id |
string |
Channel ID in the format Example: |
|
2 |
data_type |
enum (DataType) |
Data type of the returned values, see Enum "DataType". |
|
3 |
float_values |
- |
Values for DATA_TYPE_FLOAT_VALUES channels, otherwise empty, see Message "FloatValues". Time stamps and values are compared using the array index. |
|
4 |
double_values |
- |
Values for DATA_TYPE_DOUBLE_VALUES channels, otherwise empty, see Message "DoubleValues". Time stamps and values are compared using the array index. |
|
5 |
string_values |
- |
Non-equidistant values for DATA_TYPE_STRING_VALUES channels, otherwise empty, see Message "StringValues". Time stamps and values are compared by array index. |
|
6 |
digital_values |
- |
Non-equidistant rising/falling edges or gaps for DATA_TYPE_DIGITAL_VALUES channels, otherwise empty, see Message "DigitalValues". The values are valid until the next edge change, time stamp and values are matched by the array index. |
Message "FloatValues"
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
min_values |
float |
Optional: Minimum values of an aggregated channel Empty by default if not requested |
|
2 |
max_values |
float |
Optional: Maximum values of an aggregated channel Empty by default if not requested |
|
3 |
avg_values |
float |
Optional: Average values of an aggregated channel Empty by default if not requested |
Message "DoubleValues"
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
min_values |
double |
Optional: Minimum values of an aggregated channel Empty by default if not requested |
|
2 |
max_values |
double |
Optional: Maximum values of an aggregated channel Empty by default if not requested |
|
3 |
avg_values |
double |
Optional: Average values of an aggregated channel Empty by default if not requested |
Message "StringValues"
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
timestamp |
int64 |
Non-equidistant Unix time stamp in microseconds |
|
2 |
value |
value |
Non-equidistant string values |
Message "DigitalValues"
|
Pos. |
Parameter |
Data type |
Meaning |
|---|---|---|---|
|
1 |
timestamp |
int64 |
Non-equidistant Unix time stamps in microseconds |
|
2 |
value |
float |
Non-equidistant edge changes (0 or 1) or gaps (NaN) in the digital channel |
|
3 |
edgeCount |
float |
Non-equidistant edge counting of the digital channel. Indicates how often the signal value has changed in the aggregated time interval. |
|
4 |
min |
float |
Non-equidistant minimum value of the digital channel |
|
5 |
max |
float |
Non-equidistant maximum value of the digital channel |
Enum"AggregationAlgorithmType"
|
Value |
Meaning |
|
|---|---|---|
|
0 |
AGGR_ALGO_TYPE_UNSPECIFIED |
Not specified |
|
1 |
AGGR_ALGO_TYPE_MIN_MAX_AVG_DOWNSAMPLING |
Min/Max/Avg Downsampling |
|
2 |
AGGR_ALGO_TYPE_LINEAR_INTERPOLATION_DOWNSAMPLING |
Linear interpolation |
Enum "DataType"
The following values are available for DataType.
|
Value |
Meaning |
|
|---|---|---|
|
0 |
DATA_TYPE_UNSPECIFIED |
Not specified |
|
1 |
DATA_TYPE_FLOAT_VALUES |
Value of type "float" |
|
2 |
DATA_TYPE_DOUBLE_VALUES |
Value of type "double" |
|
3 |
DATA_TYPE_STRING_VALUES |
Value of type "string" |
|
4 |
DATA_TYPE_DIGITAL_VALUES |
Digital value |
|
5 |
DATA_TYPE_NE_FLOAT_VALUES |
Value of type “float” that was stored non-equidistantly |
|
6 |
DATA_TYPE_NE_DOUBLE_VALUES |
Digital value that was stored non-equidistantly |
|
7 |
DATA_TYPE_DIGITAL_EDGE_VALUES |
Number of changes of a digital non-equidistant value |