Using formula expressions
With formula expressions, you can define the mathematical functions to transform and aggregate your raw industrial data to gain insights about your operation. For more information about how to define asset properties that use formula expressions, see Transforming data (transforms) (p. 157) and Aggregating data from properties and other assets (metrics) (p. 160). Transforms and metrics are formula properties.
Topics
• Variables (p. 166)
• Literals (p. 166)
• Operators (p. 167)
• Constants (p. 169)
• Functions (p. 170)
• Formula expression tutorials (p. 198)
Variables
Variables represent AWS IoT SiteWise asset properties in formula expressions. Use variables to input values from other asset properties in your expressions, so that you can process data from constant properties (attributes (p. 154)), raw data streams (measurements (p. 155)), and other formula properties.
Variables can represent asset properties from the same asset model or from associated child asset models. Only metric formulas can input variables from child asset models.
You identify variables by different names in the console and the API.
• AWS IoT SiteWise console – Use asset property names as variables in your expressions.
• AWS IoT SiteWise API (AWS CLI, AWS SDKs) – Define variables with the ExpressionVariable structure, which requires a variable name and a reference to an asset property. The variable name can contain lowercase letters, numbers, and underscores. Then, use variable names to reference asset properties in your expressions.
Variable names are case sensitive.
For more information, see Defining transforms (p. 157) and Defining metrics (p. 160).
Literals
You can define number and string literals in formula expressions.
• Numbers
Use numbers and scientific notation to define integers and doubles. You can use E notation to express numbers with scientific notation.
Examples: 1, 2.0, .9, -23.1, 7.89e3, 3.4E-5
• Strings
Defining data properties
Use the ' (quote) and " (double quote) characters to define strings. The quote type for the start and end must match. To escape a quote that matches the one that you use to declare a string, include that quote character twice. This is the only escape character in AWS IoT SiteWise strings.
Examples: 'active', "inactive", '{"temp": 52}', "{""temp"": ""high""}"
Operators
You can use the following common operators in formula expressions.
Operator Description
+ If both operands are numbers, this operator adds
the left and right operands.
If either operand is a string, this operator concatenates the left and right operands as strings. For example, the expression 1 + 2 +
" is three" evaluates to "3 is three".
The concatenated string can have up to 1024 characters. If the string exceeds 1024 characters, then AWS IoT SiteWise doesn't output a data point for that computation.
- Subtracts the right operand from the left
operand.
You can only use this operator with numeric operands.
/ Divides the left operand by the right operand.
You can only use this operator with numeric operands.
* Multiplies the left and right operands.
You can only use this operator with numeric operands.
^ Raises the left operand to the power of the right
operand (exponentiation).
You can only use this operator with numeric operands.
% Returns the remainder from dividing the left
operand by the right operand. The result has the same sign as the left operand. This behavior differs from the modulo operation.
Defining data properties
!x Returns 1 if x is evaluated to 0 (false), otherwise
0.
x is evaluated to false if:
• x is a numeric operand and it's evaluated to 0.
• x is evaluated to an empty string.
• x is evaluated to an empty array.
• x is evaluated to None.
x and y Returns 0 if x is evaluated to 0 (false). Otherwise,
returns the evaluated result of y.
x or y is evaluated to false if:
• x or y is a numeric operand and it's evaluated to 0.
• x or y is evaluated to an empty string.
• x or y is evaluated to an empty array.
• x or y is evaluated to None.
x or y Returns 1 if x is evaluated to 1 (true). Otherwise,
returns the evaluated result of y.
x or y is evaluated to false if:
• x or y is a numeric operand and it's evaluated to 0.
• x or y is evaluated to an empty string.
• x or y is evaluated to an empty array.
• x or y is evaluated to None.
not x Returns 1 if x is evaluated to 0 (false), otherwise
0.
x is evaluated to false if:
• x is a numeric operand and it's evaluated to 0.
• x is evaluated to an empty string.
• x is evaluated to an empty array.
• x is evaluated to None.
Defining data properties
Operator Description
[]
s[index]
Returns the character at an index index of the string s. This is equivalent to the index syntax in Python.
Returns a slice of the string s. This is equivalent to the slice syntax in Python. This operator has the following arguments:
• start – (Optional) The inclusive start index of the slice. Defaults to 0.
• end – (Optional) The exclusive end index of the slice. Defaults to the length of the string.
• step – (Optional) The number to increment for each step in the slice. For example, you can specify 2 to return a slice with every other character, or specify -1 to reverse the slice.
Defaults to 1.
You can omit the step argument to use its default value. For example, s[1:4:1] is equivalent to s[1:4].
The arguments must be integers or the none (p. 170) constant. If you specify none, AWS IoT SiteWise uses the default value for that argument.
You can use the following common mathematical constants in your expressions. All constants are case insensitive.
Defining data properties
Constant Description
e The number e: 2.718281828459045
true Equivalent to the number 1. In AWS IoT SiteWise,
Booleans convert to their number equivalents.
false Equivalent to the number 0. In AWS IoT SiteWise,
Booleans convert to their number equivalents.
none
Equivalent to no value. You can use this constant to output nothing as the result of a conditional expression (p. 173).
Functions
You can use the following functions to operate on data in your formula expressions.
Transforms and metrics support different functions. The following table indicates which types of functions are compatible with each type of formula property.
Function type Transforms Metrics
Common functions (p. 171) Yes Yes
Comparison functions (p. 172) Yes Yes
Conditional functions (p. 173) Yes Yes
String functions (p. 174) Yes Yes
Aggregation functions (p. 176) No Yes
Temporal functions (p. 177) Yes Yes
Date and time
functions (p. 180) Yes Yes
Function syntax
You can use the following syntax to create functions:
Regular syntax
With the regular syntax, the function name is followed by parentheses with zero or more arguments.
function_name(argument1, argument2, argument3, ...). For example, functions with the regular syntax might look like log(x) and contains(s, substring).
Uniform function call syntax (UFCS)
UFCS enables you to call functions using the syntax for method calls in object-oriented
programming. With UFCS, the first argument is followed by dot (.), then the function name and the remaining arguments (if any) inside parentheses.
argument1.function_name(argument2, argument3, ...). For example, functions with UFCS might look like x.log() and s.contains(substring).
Defining data properties
You can also use UFCS to chain subsequent functions. AWS IoT SiteWise uses the evaluation result of the current function as the first argument for the next function.
For example, you can use message.jp('$.status').lower().contains('fail') instead of contains(lower(jp(message, '$.status')),'fail').
For more information, visit the D Programming Language website.
Note
You can use UFCS for all AWS IoT SiteWise functions.
AWS IoT SiteWise functions are not case sensitive. For example, you can use lower(s) and Lower(s) interchangeably.
Common functions
In transforms (p. 157) and metrics (p. 160), you can use the following functions to calculate common mathematical functions in transforms and metrics.
Function Description
abs(x) Returns the absolute value of x.
acos(x) Returns the arccosine of x.
asin(x) Returns the arcsine of x.
atan(x) Returns the arctangent of x.
cbrt(x) Returns the cubic root of x.
ceil(x) Returns the nearest integer greater than x.
cos(x) Returns the cosine of x.
cosh(x) Returns the hyperbolic cosine of x.
cot(x) Returns the cotangent of x.
exp(x) Returns e to the power of x.
expm1(x) Returns exp(x) - 1. Use this function to more
accurately calculate exp(x) - 1 for small values of x.
floor(x) Returns the nearest integer less than x.
log(x) Returns the loge (base e) of x.
log10(x) Returns the log10 (base 10) of x.
log1p(x) Returns log(1 + x). Use this function to more
accurately calculate log(1 + x) for small values of x.
Defining data properties
Function Description
sin(x) Returns the sine of x.
sinh(x) Returns the hyperbolic sine of x.
sqrt(x) Returns the square root of x.
tan(x) Returns the tangent of x.
tanh(x) Returns the hyperbolic tangent of x.
Comparison functions
In transforms (p. 157) and metrics (p. 160), you can use the following comparison functions to
compare two values and output 1 (true) or 0 (false). AWS IoT SiteWise compares strings by lexicographic order.
Function Description
gt(x, y) Returns 1 if x is greater than y, otherwise 0 (x >
y).
This function doesn't return a value if x and y are incompatible types, such as a number and a string.
gte(x, y) Returns 1 if x is greater than or equal to y,
otherwise 0 (x ≥ y).
AWS IoT SiteWise considers the arguments equal if they are within a relative tolerance of 1E-9. This behaves similar to the isclose function in Python.
This function doesn't return a value if x and y are incompatible types, such as a number and a string.
eq(x, y) Returns 1 if x is equal to y, otherwise 0 (x == y).
AWS IoT SiteWise considers the arguments equal if they are within a relative tolerance of 1E-9. This behaves similar to the isclose function in Python.
This function doesn't return a value if x and y are incompatible types, such as a number and a string.
neq(x, y) Returns 1 if x is not equal to y, otherwise 0 (x ==
y).
This function doesn't consider any tolerances.
This function doesn't return a value if x and y are incompatible types, such as a number and a string.
lt(x, y) Returns 1 if x is less than y, otherwise 0 (x < y).
Defining data properties
Function Description
This function doesn't return a value if x and y are incompatible types, such as a number and a string.
lte(x, y) Returns 1 if x is less than or equal to y, otherwise
0 (x ≤ y).
AWS IoT SiteWise considers the arguments equal if they are within a relative tolerance of 1E-9. This behaves similar to the isclose function in Python.
This function doesn't return a value if x and y are incompatible types, such as a number and a string.
isnan(x) Returns 1 if x is equal to NaN, otherwise 0.
This function doesn't return a value if x is a string.
Conditional functions
In transforms (p. 157) and metrics (p. 160), you can use the following function to check a condition and return different results whether the condition evaluates to true or false.
Function Description
if(condition, result_if_true, result_if_false)
Evaluates the condition and returns result_if_true if the condition evaluates to true or result_if_false if the condition evaluates to false.
condition must be a number. This function considers 0 and an empty string as false and everything else (including NaN) as true. Booleans convert to 0 (false) and 1 (true).
You can return the none constant (p. 170) from this function to discard the output for a particular condition. This means you can filter out data points that don't meet a condition. For more information, see Filtering data points (p. 199).
Example Examples
• if(0, x, y) returns the variable y.
• if(5, x, y) returns the variable x.
• if(gt(temp, 300), x, y) returns the variable x if the variable temp is greater than
Defining data properties
Function Description
We recommend that you use UFCS for nested conditional functions where one or more arguments are conditional functions. You can use if(condition, result_if_true) to evaluate a condition and elif(condition, result_if_true, result_if_false) to evaluate additional conditions.
For example, you can use if(condition1, result1_if_true).elif(condition2,
In transforms (p. 157) and metrics (p. 160), you can use the following functions to operate on strings.
For more information, see Using strings in formulas (p. 199).
Important
Formula expressions can only output double or string values. Nested expressions can output other data types, such as strings, but the formula as a whole must evaluate to a number or string. You can use the jp function (p. 174) to convert a string to a number. The Boolean value must be 1 (true) or 0 (false). For more information, see Undefined, infinite, and overflow values (p. 200).
Function Description
len(s) Returns the length of the string s.
find(s, substring) Returns the index of the string substring in the string s.
contains(s, substring) Returns 1 if the string s contains the string substring, otherwise 0.
upper(s) Returns the string s in uppercase form.
lower(s) Returns the string s in lowercase form.
jp(s, json_path)
Evaluates the string s with the JsonPath expression json_path and returns the result.
Use this function to do the following:
• Extract a value, array, or object from a serialized JSON structure.
• Convert a string to a number. For example, the formula jp('111', '$') returns 111 as a number.
Defining data properties
Function Description
To extract a string value from a JSON structure and return it as a number, you must use multiple nested jp functions. The outer jp function extracts the string from the JSON structure, and the inner jp function converts the string to a number.
The string json_path must contain a string literal. This means that json_path can't be an expression that evaluates to a string.
Example Examples
• jp('[2,8,23]', '$[2]') returns 23.
• jp('{"values":[3,6,7]}', '$.values[1]') returns 6.
• jp('111', '$') returns 111.
• jp(jp('{"measurement":
{"reading":25,"confidence":"0.95"}}', '$.measurement.confidence'), '$') returns 0.95.
join(s0, s1, s2, s3, ...) Returns a concatenated string with a delimiter.
This function uses the first input string as a delimiter and joins the remaining input strings together. This behaves similar to the join(CharSequence delimiter, CharSequence...
elements) function in Java.
Example Examples
• join("-", "aa", "bb", "cc") returns aa-bb-cc
format(expression: "format") or format("format", expression)
Returns a string in the specified format. This function evaluates expression to a value, and then returns the value in the specified format. This behaves similar to the format(String format, Object... args) function in Java. For more information about supported formats, see Conversions under Class Formatter in the Java Platform, Standard Edition 7 API Specification.
Example Examples
Defining data properties
Function Description
f'expression' Returns a concatenated string. With this
formatted function, you can use a simple expression to concatenate and format strings.
These functions may contain nested expressions.
You can use {} (curly braces) to interpolate expressions. This behaves similar to the formatted string literals in Python.
Example Examples
• f'abc{1+2: "f"}d' returns abc3.000000d.
To evaluate this example expression, do the following:
1. format(1+2: "f") returns a floating point number, 3.000000.
2. join('', "abc", 1+2, 'd') returns a string, abc3.000000d.
You can also write the expression in the following way: join('', "abc", format(1+2: "f"), 'd').
Aggregation functions
In metrics (p. 160) only, you can use the following functions that aggregate input values over each time interval and calculate a single output value. Aggregation functions can aggregate data from associated assets.
Aggregation function arguments can be variables (p. 166), number literals (p. 166), temporal functions (p. 177), nested expressions, or aggregation functions. The formula max(latest(x),
latest(y), latest(z)) uses an aggregation function as an argument and returns the largest current value of the x, y, and z properties.
You can use nested expressions in aggregation functions. When you use nested expressions, the following rules apply:
• Each argument can have only one variable.
Example
For example, avg(x*(x-1)) and sum(x/2 )/avg(y^2 ) are supported.
For example, min(x/y) isn't supported.
• Each argument can have multilevel nested expressions.
Example
For example, sum(avg(x^2 )/2) is supported.
• Different arguments can have different variables.
Example
For example, sum(x/2, y*2) is supported.
Defining data properties
Note
• If your expressions contain measurements, AWS IoT SiteWise uses the last values over the current time interval for the measurements to compute aggregates.
• If your expressions contain attributes, AWS IoT SiteWise uses the latest values for the attributes to compute aggregates.
Function Description
avg(x0, ..., xn) Returns the mean of the given variables' values over the current time interval.
This function outputs a data point only if the given variables have at least one data point over the current time interval.
sum(x0, ..., xn)
Returns the sum of the given variables' values over the current time interval.
This function outputs a data point only if the given variables have at least one data point over the current time interval.
min(x0, ..., xn) Returns the minimum of the given variables' values over the current time interval.
This function outputs a data point only if the given variables have at least one data point over the current time interval.
max(x0, ..., xn) Returns the maximum of the given variables' values over the current time interval.
This function outputs a data point only if the given variables have at least one data point over the current time interval.
count(x0, ..., xn) Returns the total number of data points for the given variables over the current time interval. For more information about how to count the number of data points that meet a condition, see Counting data points that match a condition (p. 199).
This function computes a data point for every time interval.
Temporal functions
You can use temporal functions to return values based on timestamps of data points.
Defining data properties
You can use nested expressions in temporal functions. When you use nested expressions, the following rules apply:
• Each argument can have only one variable.
For example, latest( t*9/5 + 32 ) is supported.
• Arguments can't be aggregation functions.
For example, first( sum(x) ) isn't supported.
Function Description
first(x) Returns the given variable's value with the earliest
timestamp over the current time interval.
last(x)
Returns the given variable's value with the latest timestamp over the current time interval.
earliest(x) Returns the given variable's value with the earliest
timestamp before the current time interval.
This function computes a data point for every time interval, if the input property has at least one data point in its history.
latest(x)
Returns the given variable's value with the latest timestamp before the end of the current time interval.
This function computes a data point for every time interval, if the input property has at least one data point in its history.
statetime(x)
Returns the amount of time in seconds that the given variables are positive over the current time interval. You can use the comparison functions (p. 172) to create a transform property for the statetime function to consume.
For example, if you have an Idle property that is 0 or 1, you can calculate idle time per time interval with this expression: IdleTime = statetime(Idle). For more information, see the example statetime scenario (p. 179).
This function doesn't support metric properties as input variables.
This function computes a data point for every time interval, if the input property has at least one data point in its history.
The following diagram shows how AWS IoT SiteWise computes the temporal functions first, last, earliest, and latest, relative to the current time interval.
Defining data properties
Example Example statetime scenario
Consider an example where you have an asset with the following properties:
• Idle – A measurement that is 0 or 1. When the value is 1, the machine is idle.
• Idle Time – A metric that uses the formula statetime(Idle) to calculate the amount of time in seconds where the machine is idle, per 1 minute interval.
The Idle property has the following data points.
Timestamp 2:00:00 PM 2:00:30 PM 2:01:15 PM 2:02:45 PM 2:04:00 PM
Idle 0 1 1 0 0
AWS IoT SiteWise calculates the Idle Time property every minute from the values of Idle. After this calculation completes, the Idle Time property has the following data points.
Timestamp 2:00:00 PM 2:01:00 PM 2:02:00 PM 2:03:00 PM 2:04:00 PM
Idle Time N/A 30 60 45 0
AWS IoT SiteWise performs the following calculations for Idle Time at the end of each minute.
• At 2:00 PM (for 1:59 PM to 2:00 PM)
• There is no data for Idle before 2:00 PM, so no data point is calculated.
• At 2:01 PM (for 2:00 PM to 2:01 PM)
• At 2:00:00 PM, the machine is active (Idle is 0).
• At 2:00:30 PM, the machine is idle (Idle is 1).
• Idle doesn't change again before the end of the interval at 2:01:00 PM, so Idle Time is 30 seconds.
• At 2:02 PM (for 2:01 PM to 2:02 PM)
• At 2:01:00 PM, the machine is idle (per the last data point at 2:00:30 PM).
• At 2:01:15 PM, the machine is still idle.
• Idle doesn't change again before the end of the interval at 2:02:00 PM, so Idle Time is 60 seconds.
• At 2:03 PM (for 2:02 PM to 2:03 PM)
• At 2:02:00 PM, the machine is idle (per the last data point at 2:01:15 PM).
Defining data properties
Using temporal functions in transforms
In transforms (p. 157) only, you can use the pretrigger() function to retrieve the GOOD quality value for a variable prior to the property update that triggered the current transform calculation.
Consider an example where a manufacturer uses AWS IoT SiteWise to monitor the status of a machine.
The manufacturer uses the following measurements and transforms to represent the process:
The manufacturer uses the following measurements and transforms to represent the process: