Sampling()

Format

Sampling(Expr, Method[, Interval])

Purpose

Overrides the sample method and/or sample interval passed to tags referenced within the expression. 
This function should only be used with time series data.

Related: Data Transformation and Sample Methods

Inputs

Expr: The expression containing the tags to be fetched.
Behaviour: Required
Dimension: Collection, SingleValue, Matrix, Error, MultiCollection
Valid data types: Boolean, DateTime, Decimal, Integer, String, Duration, Error, Null

Method: Fetch tags using the specified sample method.  
Options: "average", "linearinterpolate", "lastknownvalue", "raw"
Behaviour: Required

Interval: Fetch tags using the specified sample interval.
Behaviour: Optional
Dimension: SingleValue
Valid data types: Decimal, Integer, Duration

Notes:
- When intervals are expressed as numbers (decimal or integer), they are interpreted as seconds.
- Decimals are expressed by using a decimal point and at least 1 decimal number e.g. 60.0

Examples

Expression: Sampling({tagname}, "raw")
Result: Fetch tags using the Raw sample method

Expression: Sampling({tagname}, "average", 60)
Result: Fetch tags using the Average sample method, with an interval of 60 seconds expressed as an integer.

Expression: Sampling({tagname}, "lastknownvalue", 60.0)
Result: Fetch tags using the Last Known Value sample method, with an interval of 60 seconds expressed as a decimal.

Expression: Sampling({tagname}, "linearinterpolate", {du'0:01'})
Result: Fetch tags using the Linear Interpolate sample method, with an interval of 1 minute expressed as a duration.

The following trend shows the {Silver} tag with different sampling methods being overridden using Sampling().

 

 

Expression: Sampling({Entity[Template]:Attribute!AttributeValue}, "raw")
Result: Fetch the attribute using the Raw sample method.

It is possible to retrieve very large volumes of data through indiscriminate use of the raw sample method. Retrieving large amounts of historian data across a slow network can affect system performance for all users of the system.

The following trend shows an attribute being trended using the Raw sampling method.

 

Expression: Sampling({tagname}/100, "average", 3600)
Result: Fetch the tag and divide it by 100, then apply the Average sample method and a sample interval of 3600 seconds (1 hour).

The following trend shows the Silver tag being divided by 100 and then trended using the Average sampling method with a sample interval of 3600 seconds.

Using Sampling() instead of Tag Syntax:

Sampling() can be used as a shortcut for expressions using tag syntax, typically used when overriding context parameters. For example:

This expression:

Sampling({myTag}, "LastKnownValue", {du'01:00'})

Is the same as:

{myTag, sampleMethod="LastKnownValue", sampleInterval={du'01:00'}}

Common Traps

Empty strings for the sample method are not accepted. E.g. The following example is not valid:

Sampling({tagname}, "", 60)

Expected result: Override only the sample interval but not the sample method while fetching tags.
Actual result: Calculation cannot be parsed as empty strings are not accepted. The equivalent correct call is: 
Sampling({tagname}, param[sampleMethod], 60)

It is possible to retrieve very large volumes of data through indiscriminate use of this function. Retrieving large amounts of historian data across a slow network can affect system performance for all users of the system.

Release History

• Sampling() 4.6.5
  • Changed Expr parameter to support MultiCollection values.
• Sampling() 4.0
  • Initial version