Query Modifiers

Query Modifiers are used for retrieving data that has been stored in the archive. They are used along with sampling and calculation modes to get a specific set of data.


Query Modifier	Results
ONLYGOOD	The ONLYGOOD modifier excludes bad and uncertain data quality values from retrieval and calculations. Use this modifier with any sampling or calculation mode but it is most useful with Raw and CurrentValue queries. All the calculation modes such as minimum or average exclude bad values by default, so this modifier is not required with those.
INCLUDEREPLACED	Normally, when you query raw data from Proficy Historian, any values that have been replaced with a different value for the same timestamp are not returned. The INCLUDEREPLACED modifier helps you to indicate that you want replaced values to be returned, in addition to the currently retrievable data. However, you cannot query only the replaced data and the retrievable values that have replaced the other values. You can query all currently visible data and get the data that has been replaced. This modifier is only useful with rawbytime or rawbynumber retrieval. Do not use it with any other sampling or calculation mode.
INCLUDEDELETED	The INCLUDEDELETED modifier retrieves the value that was previously deleted. Data that has been deleted from the archiver is never actually removed but is marked as hidden. Use the INCLUDEDELETED modifier to retrieve the values that were deleted, in addition to any non-deleted values during the query time period. This modifier is only useful with rawbytime or rawbynumber retrieval. Do not use it with any other sampling or calculation mode.
ONLYIFCONNECTED ONLYIFUPTODATE	The ONLYIFCONNECTED and ONLYIFUPTODATE modifiers can be used on any sampling or calculation mode to retrieve bad data if the collector is not currently connected and sending data to the archiver. The bad data is not stored in the IHA file but is only returned in the query. If the collector reconnects and flushes data and you run the query again, the actual stored data is returned in the following situations: Collector loses connection to the archiver Collector crashes Collector compression is used and no value exceeds the dead band
ONLYRAW	The ONLYRAW modifier retrieves only the raw stored samples. It does not add interpolated or lab sampled values at the beginning of each interval during calculated retrieval such as average or minimum or maximum. Normally, a data query for minimum value will interpolate a value at the start of each interval and use that together with any raw samples to determine the minimum value in the interval. Interpolation is necessary because some intervals may not have any raw samples stored. Use this query modifier with calculation modes only, not with raw or sampled retrieval like interpolated modes.
LABSAMPLING	The LABSAMPLING modifier affects the calculation modes that interpolate a value at the start of each interval. Instead of using interpolation, lab sampling is used. When querying highly compressed data, you may have intervals with no raw samples stored. An average from 2 PM to 6 PM on a one-hour interval will interpolate a value at 2 PM, 3 PM, 4 PM, and 5 PM and use those in addition to any stored samples to compute averages. When you specify LABSAMPLING, then lab sampling mode is used instead of interpolated sampling mode to determine the 2 PM, 3 PM, 4 PM, and 5 PM values. A lab sampled average would be used when querying a tag that never ramps but changes in a step pattern such as a state value or setpoint. Use this query modifier with calculation modes only, not raw or sampled retrieval like interpolated modes.
ENUMNATIVEVALUE	The ENUMNATIVEVALUE modifier retrieves the native, numeric values such as 1 or 2 instead of string values such as on/off for the data that has enumerated states associated with it. You can use ENUMNATIVEVALUE with any sampling or calculation mode.
INCLUDEBAD	Normally, when you query calculated data from Historian, only good data quality raw samples are considered. INCLUDEBAD modifier includes bad data quality values in calculations. You can use INCLUDEBAD with any sampling or calculation mode.
FILTERINCLUDEBAD	Typically, while filtering we use only good data quality values. When we use FILTERINCLUDEBAD, the bad data quality values are considered when filtering to determine time ranges. This query modifier is not always recommended.
USEMASTERFIELDTIME	The USEMASTERFIELDTIME query modifier is used only for the MultiField tags. It returns the value of all the fields at the same timestamp of the master field time, in each interval returned.
HONORENDTIME	Normally, a query keeps searching through archives until the desired number of samples has been located, or until it gets to the first or last archive. However, there are cases where you would want to specify a time limit as well. For example, you may want to output the returned data for a RawByNumber query in a trend screen, in which case there is no need to return data that would be offscreen. In cases where you want to specify a time limit, you can do this by specifying an end time in your RawByNumber query and including the HONORENDTIME query modifier. Since RawByNumber has direction (backward or forward), the end time must be older than the start time for a backward direction or newer than the start time for a forward direction. Use this query modifier only with the RawByNumber sampling mode.
EXAMINEFEW	Queries using calculation modes normally loop through every raw sample, between the given start time and end time, to compute the calculated values. When using FirstRawValue, FirstRawTime, LastRawValue, and LastRawTime calculation modes, we can use only the raw sample near each interval boundary and achieve the same result. The EXAMINEFEW query modifier enables this. If you are using one of these calculation modes, you may experience better read performance using the EXAMINEFEW query modifier. Using this query modifier is recommended when: The time interval is great than 1 minute. The collection interval is greater than 1 second. The data node size is greater than the default 1400 bytes. The data type of the tags is String or Blob. Query performance varies depending on all of the above factors. Use this query modifier only with FirstRawValue, FirstRawTime, LastRawValue, and LastRawTime calculation modes.
EXCLUDESTALE	Stale tags are tags that have no new data samples within a specified period of time, and which have the potential to add to system overhead and slow down user queries. The EXCLUDESTALE query modifier allows for exclusion of stale tags in data queries. Unless permanently deleted, stale tags from the archiver are not removed but are simply marked as stale. Use the query without this query modifier to retrieve the sample values. Data is not returned for stale tags. An ihSTATUS_STALED_TAG error is returned instead.