Issues a query to to the SQLTags Historian. Querying tag history involves specifying the tags and the date range, as well as a few optional parameters. The SQLTags 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 also: Tag Paths.
The return size determines how the underlying data is aggregated and/or interpolated. If a distinct return size is specified, that will be the number of rows in the resulting dataset. The special numbers 0 and -1 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.
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 only "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.
The aggregation mode is used when the data is denser than what you asked for. 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:
This function accepts keyword-style invocation. See also: Functions / Keyword Invocation
system.tag.queryTagHistory(paths, startDate, endDate, returnSize, aggregationMode, returnFormat, columnNames, intervalHours, intervalMinutes, rangeHours, rangeMinutes)
PySequence 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.
Date endDate - The latest value to retrieve. If omitted, current time is used.
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.
String aggregationMode - The mode to use when aggregating multiple samples into one time slice. Must be one of "Average" or "MinMax".
String returnFormat - Use "Wide" to have a column per tag queried, or "Tall" to have a fixed-column format. Default is "Wide".
PySequence 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.
Integer intervalHours - Allows you to specify the window interval in terms of hours, as opposed to using a specific return size.
Integer intervalMinutes - Same as intervalHours, but in minutes. Can be used on its own, or in conjunction with intervalHours.
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.
Integer rangeMinutes - Same as rangeHours, but in minutes.
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.