system.historian.queryRawPoints

This function is used in Python Scripting.

Description

Queries raw data points for the specified historian. Querying a historian involves specifying the node paths and the date range, as well as a few optional parameters. The historian will find the relevant history, then interpolate and aggregate it into a coherent, tabular result set.

This function is useful when you're trying to retrieve historian 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.historian.queryAggregatedPoints.

note

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

Parameter Considerations

The returnSize 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 to 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.

note

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. 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.

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.historian.queryRawPoints(paths, startTime, endTime, [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	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. This parameter is only supported for the Internal Historian and the Core Historian. [Optional]
Boolean	includeBounds	Whether to include the bounds in the query results.
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 raw data points for the specified historical paths.

Scope

Gateway, Vision Client, Perspective Session

Code Examples

Code Snippet 1

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

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

myDataset = system.historian.queryRawPoints(["[default]_Simulator_/Random/RandomInteger1"], start, end, includeBounds=False)

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

Code Snippet 2

# Query specified historian tag paths and display raw data from within the past hour 
# applying alias column names and return size and format configurations.

results = system.historian.queryRawPoints(
  paths=[
      "histprov:CoreHistorian:/sys:gateway:/prov:default:/tag:Folder/MyTag",
      "histprov:CoreHistorian:/sys:gateway:/prov:default:/tag:Folder/OtherTag"
  ],
  startTime=system.date.addHours(system.date.now(), -1),
  endTime=system.date.now(),
  columnNames=["MyTagAlias", "OtherTagAlias"],
  returnFormat="WIDE",
  returnSize=1000,
  includeBounds=True,
  excludeObservations=False
)

for row in results:
    print results["timestamp"], results["MyTagAlias"]