system.historian.queryAggregatedPoints

This function is used in Python Scripting.

Description

Queries aggregated data points for a historian over a specified time range. This function takes a list of strings, where each string is a path to a historical node.

This is useful when you wish to aggregate historian data collected over a period of time into a single value per aggregate. If you want multiple values aggregated to a single time slice, such as hourly aggregates for the same tag over an 8-hour period, consider using system.historian.queryRawPoints.

note

Make sure the deadband style is set to Discrete Mode if you do not want seed values included in the raw data returned.

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.historian.queryAggregatedPoints(paths, startTime, endTime, [aggregates], [fillModes], [columnNames], [returnFormat], [returnSize], [includeBounds], [excludeObservations])

Parameters

Type	Parameter	Description
List	paths	A list of historical paths to query aggregated data points for. See Path Syntax for more information on recommended syntax.
Date	startTime	A start time to query aggregated data points for.
Date	endTime	An end time to query aggregated data points for.
List	aggregates	A list of aggregate functions to apply to the query. [Optional] Available aggregates include: Average: Time-weighted average SimpleAverage: Sum/count Sum: Sum of values Minimum: Minimum value Maximum: Maximum value MinMax: Both min and max LastValue: Value at window boundary Range: Max minus min Count: Count of good, non-interpolated values CountOn: Transitions to true CountOff: Transitions to false DurationOn: Seconds value was true DurationOff: Seconds value was false Variance: Statistical variance StdDev: Standard deviation PctGood: Percentage time good quality PctBad: Percentage time bad quality
List	fillModes	A list of fill modes to apply to the query. The fill mode will override the tag's stored interpolation mode at query time. For example, if a tag stores with analog mode (linear), but you want to query as discrete (prev), specify fillModes=['PREV']. This parameter is only functional with the Core Historian and the Internal Historian. [Optional] Available options include: DERIVED: Use tag's stored interpolation mode (linear for analog, prev for discrete) LINEAR: Linear PREV: Repeat last known value NULL: Fill with nulls NONE: Exclude missing windows
List	columnNames	A list of alias column names for the returned dataset. [Optional]
String	returnFormat	The desired return format for the query. [Optional] Available options include: WIDE: One value per path per row: [path1_val, path2_val, ..., timestamp] (default) TALL: One value per row: [path, value, quality, timestamp] CALCULATION: Calculated result per path aggregate
Integer	returnSize	The maximum number of results to return. [Optional]
Boolean	includeBounds	Whether to include the bounds in the query results. [Optional]
Boolean	excludeObservations	Whether to exclude observed aggregated data points in the query results. When applied, observed values, such as periodic samples from Tag Group evaluations will be filtered out, while source values, such as tag changes from devices will remain in the returned dataset. [Optional]

Returns

Dataset - A dataset representing the aggregated values for the specified historical paths. A demonstration of the table is shown below. There is a row per tag ID, and a column per requested calculation. The tag is returned in the first column.

tag	calculation1	calculation2	calculationN
path1	value	value	value
path2	value	value	value
pathN	value	value	value

Scope

Gateway, Vision Client, Perspective Session

Code Examples

Code Snippet 1

# Query a specified historical simulator tag path and display aggregated data from within the past minute.

end = system.date.now()
start = system.date.addMinutes(end, -1)

myDataset = system.historian.queryAggregatedPoints(["histprov:MySQL:/sys:gw1:/prov:default:/tag:Simulator_/Random/RandomInteger1"], start, end)

for row in myDataset:
    print row[0], row[1]

Code Snippet 2

# Query a specified historical simulator tag path and display the sum of the aggregated data 
# from within the past minute in Wide format.

path = ["histprov:MySQL:/sys:gw1:/prov:default:/tag:Simulator_/Random/RandomInteger1"]
start = system.date.addMinutes(end, -1)
end = system.date.now()

aggregates = ["Sum"]
fillModes = ['NONE']
returnFormat = 'Wide'
returnSize = 1

historyHistorian = system.historian.queryAggregatedPoints(
    path, 
    start, 
    end, 
    aggregates, 
    fillModes=fillModes, 
    returnFormat=returnFormat, 
    returnSize=returnSize)

for row in historyHistorian: 
    print row [0], row[1]