Formula expression tutorials
You can follow these tutorials to use formula expressions in AWS IoT SiteWise.
Topics
Using strings in formulas
You can operate on strings in your formula expressions. You also can input strings from variables that reference attribute and measurement properties.
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 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.
AWS IoT SiteWise provides the following formula expression features that you can use to operate on strings:

The index operator (
s[index]
) 
The slice operator (
s[start:end:step]
) 
Comparison functions, which you can use compare strings by lexicographic order

String functions, which includes the
jp
function that can parse serialized JSON objects and convert strings to numbers
Filtering data points
You can use the if function to filter out
data points that don't meet a condition. The if
function evaluates a
condition and returns different values for true
and false
results. You can use the none constant as an
output for one case of an if
function to discard the data point for that
case.
To filter out data points that match a condition

Create a transform that uses the
if
function to define a condition that checks if a condition is met, and returnsnone
as either theresult_if_true
orresult_if_false
value.
Example: Filter out data points where water isn't boiling
Consider a scenario where you have a measurement, temp_c
, that
provides the temperature (in Celsius) of water in a machine. You can define the
following transform to filter out data points where the water isn't boiling:

Transform:
boiling_temps = if(gte(temp_c, 100), temp_c, none)
– Returns the temperature if it's greater than or equal to 100 degrees Celsius, otherwise returns no data point.
Counting data points that match a condition
You can use comparison functions and sum() to count the number of data points for which a condition is true.
To count data points that match a condition

Create a transform that uses a comparison function to define a filter condition on another property.

Create a metric that sums the data points where that condition is met.
Example: Count the number of data points where water is boiling
Consider a scenario where you have a measurement, temp_c
, that
provides the temperature (in Celsius) of water in a machine. You can define the
following transform and metric properties to count the number of data points where
the water is boiling:

Transform:
is_boiling = gte(temp_c, 100)
– Returns1
if the temperature is greater than or equal to 100 degrees Celsius, otherwise returns0
. 
Metric:
boiling_count = sum(is_boiling)
– Returns the number of data points where water is boiling.
Late data in formulas
AWS IoT SiteWise supports late data ingestion of data that is up to 7 days old. When AWS IoT SiteWise receives late data, it recalculates existing values for any metric that inputs the late data in a past window. These recalculations result in data processing charges.
Note
When AWS IoT SiteWise computes properties that input late data, it uses each property's current formula expression.
After AWS IoT SiteWise recalculates a past window for a metric, it replaces the previous value for that window. If you enabled notifications for that metric, AWS IoT SiteWise also emits a property value notification. This means that you can receive a new property value update notification for the same property and timestamp for which you previously received a notification. If your applications or data lakes consume property value notifications, you must update the previous value with the new value so that their data is accurate.
Data quality in formulas
In AWS IoT SiteWise, each data point has a quality code, which can be one of the following:

GOOD
– The data isn't affected by any issues. 
BAD
– The data is affected by an issue such as sensor failure. 
UNCERTAIN
– The data is affected by an issue such as sensor inaccuracy.
AWS IoT SiteWise consumes only GOOD
quality data when it computes transforms
and metrics. AWS IoT SiteWise outputs only GOOD
quality data for successful
computations. If a computation is unsuccessful, then AWS IoT SiteWise doesn't output a data
point for that computation. This can occur if a computation results in an undefined,
infinite, or overflow value.
For more information about how to query data and filter by data quality, see Querying asset property values and aggregates.
Undefined, infinite, and overflow values
Some formula expressions (such as x / 0
, sqrt(1)
, or
log(0)
) calculate values that are undefined in a real number system,
infinite, or outside the range supported by AWS IoT SiteWise. When an asset property's
expression computes an undefined, infinite, or overflow value, AWS IoT SiteWise doesn't output a
data point for that computation.
AWS IoT SiteWise also doesn't output a data point if it computes a nonnumeric value as the result of a formula expression. This means that if you define a formula that computes a string, array, or the none constant, then AWS IoT SiteWise doesn't output a data point for that computation.
Examples
Each of the following formula expressions result in a value that AWS IoT SiteWise can't represent as a number. AWS IoT SiteWise doesn't output a data point when it computes these formula expressions.

x / 0
is undefined. 
log(0)
is undefined. 
sqrt(1)
is undefined in a real number system. 
"hello" + " world"
is a string. 
jp('{"values":[3,6,7]}', '$.values')
is an array. 
if(gte(temp, 300), temp, none)
isnone
whentemp
is less than300
.