system.tag.queryTagHistory
This function is used in Python Scripting.
Description​
Issues a query to the Tag Historian. Querying tag history involves specifying the tags and the date range, as well as a few optional parameters. The Tag Historian will find the relevant history and then interpolate and aggregate it together into a coherent, tabular result set. This function takes a list of strings, where each string is a tag path, like Tanks/Tank5 or [OracleProvider]Sump/Out2. See Tag Paths for more information.
This is useful when you're trying to retrieve tag history data over a period of time. However, if you are trying to take a range of time and aggregate the data to a single value, consider using system.tag.queryTagCalculations.
The return size determines how the underlying data is aggregated and interpolated. If a distinct return size is specified, that will be the number of rows in the resulting dataset. You can use special numbers 0 and -1 that mean "Natural" and "On-Change", respectively. Natural calculates a return size based on the rate of the logging historical scan classes. For example, if you query 1 hour of data for a scan class logging every minute, the natural return size is 60. On-Change means that you'll get an entry whenever any of the tags under consideration have changed. Instead of defining a fixed return size, the parameters intervalHours and intervalMinutes can be used. These parameters can be used independently or together to define a window size. For example, if you defined a 1 hour range, with intervalMinutes=15, you would get 4 rows as a result.
Make sure the deadband style is set to Discrete Mode if you do not want seed values included in the raw data returned.
The span of the query can be specified using startDate and endDate. You can also use rangeHours and rangeMinutes in conjunction with either start or end date to specify the range in dynamic terms. For example, you could specify "rangeHours=-8" to get the last 8 hours from the current time. Or you could use "startDate='2012-05-30 00:00:00', rangeHours=12" to get the first half of the day for May 30th, 2012.
Please note that intervals returned by Historical queries are inclusive of the endDate, including when the endDate is set to now(). This means you may see one additional interval than expected that only contains future dates, which get interpolated to 0 and can cause trending issues.
For example, if you want data from 10am - 11am in 1 minute windows, you’ll need to set your query from 10am-10:59am. Querying to 11am would create an interval to contain it and that window will often return 0 since there is typically no future value. Additionally, if you went on to add the results of two queries of adjoining times, such as 10am - 11am and 11am - 12pm, the first window of the second period would have duplicate data to the last window of the first period.
The aggregation mode is used when the data is denser than what your request. This happens when using fixed return sizes, as there will often be multiple raw values for the window interval defined. Another common operation is to set the return size to 1, in order to use these aggregate functions for calculation purposes. The available functions are:
- "MinMax" - Will return two entries per time slice - the min and the max.
- "Average" - Will return the time-weighted average value of all samples in that time slice.
- "LastValue" -Returns the most recent actual value to the end of the window. Note that if a value does not exist in this window, a 0 will be returned in cases where interpolation is turned on.
- "Sum" - The values in the time slice are added together.
- "SimpleAverage" - Returns the simple mathematical average of the values - ((V 1 +V 2 +...+V n )/n)
- "Maximum" - The maximum value of the window.
- "Minimum" - The minimum value of the window.
- "DurationOn" - The time, in seconds, that a value has been boolean true.
- "DurationOff" - The time, in seconds, that a value has been boolean false.
- "CountOn" - The number of times the value has transitioned to boolean true.
- "CountOff" - The number of times the value has transitioned to boolean false.
- "Count" - The number of "good", non-interpolated values per window.
- "Range" - The difference between the min and max.
- "Variance" - The variance for "good", non-interpolated values. Does not time weight.
- "StdDev" - The standard deviation for "good", non-interpolated values. Does not time weight.
- "PctGood" - The percentage of time the value was good.
- "PctBad" - The percentage of time the value was bad.
Client Permission Restrictions​
This scripting function has no Client Permission restrictions.
Syntax​
This function accepts keyword arguments.
system.tag.queryTagHistory(paths, [startDate], [endDate], [returnSize], [aggregationMode], [returnFormat], [columnNames], [intervalHours], [intervalMinutes], [rangeHours], [rangeMinutes], [aggregationModes], [includeBoundingValues], [validateSCExec], [noInterpolation], [ignoreBadQuality], [timeout], [intervalSeconds], [rangeSeconds])
Parameters​
| Type | Parameter | Description |
|---|---|---|
| List[String] | paths | An array of tag paths (strings) to query. Each tag path specified will be a column in the result dataset. |
| Date | startDate | The earliest value to retrieve. If omitted, 8 hours before current time is used. [optional] |
| Date | endDate | The latest value to retrieve. If omitted, current time is used. [optional] |
| Integer | returnSize | The number of samples to return. -1 will return values as they changed, and 0 will return the "natural" number of values based on the logging rates of the scan class(es) involved. -1 is the default. [optional] |
| String | aggregationMode | The mode to use when aggregating multiple samples into one time slice. Valid values are: "Average" (time-weighted), "MinMax", "LastValue", "SimpleAverage", "Sum", "Minimum", "Maximum", "DurationOn", "DurationOff", "CountOn", "CountOff", "Count", "Range", "Variance", "StdDev", "PctGood", and "PctBad". Default is "Average" (time-weighted). [optional] |
| String | returnFormat | Use "Wide" to have a column per tag queried, or "Tall" to have a fixed-column format. Default is "Wide". [optional] |
| List[String] | columnNames | Aliases that will be used to override the column names in the result dataset. Must be 1-to-1 with the tag paths. If not specified, the Tag paths themselves will be used as column titles. [optional] |
| Integer | intervalHours | Allows you to specify the window interval in terms of hours, as opposed to using a specific returnSize. The Historian will use the intervalHours value to determine the return size automatically based on the start and end date. For example, if your start and end date are 12 hours apart, and you pass an interval of 2 hours, the Historian will calculate your return size as 6. If you specify a returnSize, all interval parameters are ignored. [optional] |
| Integer | intervalMinutes | Same as intervalHours, but in minutes. Can be used on its own, or in conjunction with intervalHours. [optional] |
| Integer | rangeHours | Allows you to specify the query range in hours, instead of using start and end date. Can be positive or negative, and can be used in conjunction with startDate or endDate. [optional] |
| Integer | rangeMinutes | Same as rangeHours, but in minutes. [optional] |
| List[String] | aggregationModes | A one-to-one list with paths specifying an aggregation mode per column. [optional] |
| Boolean | includeBoundingValues | A boolean flag indicating that the system should attempt to include values for the query bound times if possible. The default for this property depends on the query mode. For more information see Seeded Values. [optional] |
| Boolean | validateSCExec | A boolean flag indicating whether or not data should be validated against the scan class execution records. If false, data will appear flat (but good quality) for periods of time in which the system wasn't running. If true, the same data would be bad quality during downtime periods. [optional] |
| Boolean | noInterpolation | A boolean flag indicating that the system should not attempt to interpolate values in situations where it normally would. This will also prevent the return of rows that are purely interpolated. [optional] |
| Boolean | ignoreBadQuality | A boolean flag indicating that bad quality values should not be used in the query process. If set, any value with a "bad" quality will be completely ignored in calculations and in the result set. [optional] |
| Integer | timeout | Timeout in milliseconds for Client Scope. This property is ignored in the Gateway Scope. [optional] |
| Integer | intervalSeconds | ​ New in 8.1.0 Same as intervalHours and interval Minutes, but in seconds. Can be used on its own, or in conjunction with intervalHours and intervalMinutes. [optional] |
| Integer | rangeSeconds | ​ New in 8.1.0 Allows you to specify the query range in seconds, instead of using start and end date. Can be positive or negative, and can be used in conjunction with startDate or endDate. [optional] |
Returns​
Dataset - A dataset representing the historian values for the specified tag paths. The first column will be the timestamp, and each column after that represents a tag.
Scope​
Gateway, Vision Client, Perspective Session
Code Examples​
# The following example will return a dataset with one row detailing maximum value of a Tag named 'Sine' for the past 30 minutes.
endTime = system.date.now()
startTime = system.date.addMinutes(endTime, -30)
dataSet = system.tag.queryTagHistory(paths=['Sine'], startDate=startTime, endDate=endTime, returnSize=1, aggregationMode="Maximum", returnFormat='Wide')