End of support notice: On May 20, 2026, AWS will end support for AWS IoT Events. After May 20, 2026, you will no longer be able to access the AWS IoT Events console or AWS IoT Events resources. For more information, see [AWS IoT Events end of support](https://docs.aws.amazon.com/iotevents/latest/developerguide/iotevents-end-of-support.html). # Expressions to filter, transform, and process event data Expressions Expressions are used to evaluate incoming data, perform calculations, and determine the conditions under which specific actions or state transitions should occur. AWS IoT Events provides several ways to specify values when you create and update detector models. You can use expressions to specify literal values, or AWS IoT Events can evaluate the expressions before you specify particular values. **Topics** + [ ## Syntax to filter device data and define actions in AWS IoT Events ](#expression-syntax) + [ # Expression examples and usage for AWS IoT Events ](expression-usage.md) ## Syntax to filter device data and define actions in AWS IoT Events Syntax to filter device data Expressions offer syntax for filtering device data and defining actions. You can use literals, operators, functions, references, and substitution templates in the AWS IoT Events expressions. By combining these components, you can create powerful and flexible expressions to process IoT data, perform calculations, manipulate strings, and make logical decisions within your detector models. ### Literals + Integer + Decimal + String + Boolean ### Operators Unary + Not (Boolean): `!` + Not (bitwise): `~` + Minus (arithmetic): `-` String + Concatenation: **`+`** Both operands must be strings. String literals must be enclosed in single quotes ('). For example: `'my' + 'string'` -> `'mystring'` Arithmetic + Addition: **`+`** Both operands must be numeric. + Subtraction: **`-`** + Division: **`/`** The result of the division is a rounded integer value unless at least one of the operands (divisor or dividend) is a decimal value. + Multiplication: **`*`** Bitwise (Integer) + OR: **`|`** For example: `13 | 5` -> `13` + AND: **`&`** For example: `13 & 5` -> `5` + XOR: **`^`** For example: `13 ^ 5` -> `8` + NOT: **`~`** For example: `~13` -> `-14` Boolean + Less Than: **`<`** + Less Than Or Equal To: **`<=`** + Equal To: **`==`** + Not Equal To: **`!=`** + Greater Than Or Equal To: **`>=`** + Greater Than: **`>`** + AND: **`&&`** + OR: **`||`** **Note** When a subexpression of `||` contains undefined data, that subexpression is treated as `false`. Parentheses You can use parentheses to group terms within an expression. ### Functions to use in AWS IoT Events expressions Functions for expressions AWS IoT Events provides a set of built-in functions to enhance the capabilities of your detector model expressions. These functions enable timer management, type conversion, null checking, trigger type identification, input verification, string manipulation, and bitwise operations. By leveraging these functions, you can create a responsive AWS IoT Events processing logic, improving the overall effectiveness of your IoT applications. Built-in Functions `timeout("timer-name")` Evaluates to `true` if the specified timer has elapsed. Replace "**timer-name**" with the name of a timer that you defined, in quotation marks. In an event action, you can define a timer and then start the timer, reset it, or clear one that you previously defined. See the field `detectorModelDefinition.states.onInput|onEnter|onExit.events.actions.setTimer.timerName`. A timer set in one state can be referenced in a different state. You must visit the state in which you created the timer before you enter the state in which the timer is referenced. For example, a detector model has two states, `TemperatureChecked` and `RecordUpdated`. You created a timer in the `TemperatureChecked` state. You must visit the `TemperatureChecked` state first before you can use the timer in the `RecordUpdated` state. To ensure accuracy, the minimum time that a timer should be set is 60 seconds. `timeout()` returns `true` only the first time it's checked following the actual timer expiration and returns `false` thereafter. `convert(type, expression)` Evaluates to the value of the expression converted to the specified type. The *type* value must be `String`, `Boolean`, or `Decimal`. Use one of these keywords or an expression that evaluates to a string containing the keyword. Only the following conversions succeed and return a valid value: + Boolean -> string Returns the string `"true"` or `"false"`. + Decimal -> string + String -> Boolean + String -> decimal The string specified must be a valid representation of a decimal number, or `convert()` fails. If `convert()` doesn't return a valid value, the expression that it's a part of is also invalid. This result is equivalent to `false` and won't trigger the `actions` or transition to the `nextState` specified as part of the event in which the expression occurs. `isNull(expression)` Evaluates to `true` if the expression returns null. For example, if the input `MyInput` receives the message `{ "a": null }`, then the following evaluates to `true`, but `isUndefined($input.MyInput.a)` evaluates to `false`. ``` isNull($input.MyInput.a) ``` `isUndefined(expression)` Evaluates to `true` if the expression is undefined. For example, if the input `MyInput` receives the message `{ "a": null }`, then the following evaluates to `false`, but `isNull($input.MyInput.a)` evaluates to `true`. ``` isUndefined($input.MyInput.a) ``` `triggerType("type")` The *type* value can be `"Message"` or `"Timer"`. Evaluates to `true` if the event condition in which it appears is being evaluated because a timer has expired like in the following example. ``` triggerType("Timer") ``` Or an input message was received. ``` triggerType("Message") ``` `currentInput("input")` Evaluates to `true` if the event condition in which it appears is being evaluated because the specified input message was received. For example, if the input `Command` receives the message `{ "value": "Abort" }`, then the following evaluates to `true`. ``` currentInput("Command") ``` Use this function to verify that the condition is being evaluated because a particular input has been received and a timer hasn't expired, as in the following expression. ``` currentInput("Command") && $input.Command.value == "Abort" ``` String Matching Functions `startsWith(expression1, expression2)` Evaluates to `true` if the first string expression starts with the second string expression. For example, if input `MyInput` receives the message `{ "status": "offline"}`, then the following evaluates to `true`. ``` startsWith($input.MyInput.status, "off") ``` Both expressions must evaluate to a string value. If either expression does not evaluate to a string value, then the result of the function is undefined. No conversions are performed. `endsWith(expression1, expression2)` Evaluates to `true` if the first string expression ends with the second string expression. For example, if input `MyInput` receives the message `{ "status": "offline" }`, then the following evaluates to `true`. ``` endsWith($input.MyInput.status, "line") ``` Both expressions must evaluate to a string value. If either expression does not evaluate to a string value, then the result of the function is undefined. No conversions are performed. `contains(expression1, expression2)` Evaluates to `true` if the first string expression contains the second string expression. For example, if input `MyInput` receives the message `{ "status": "offline" }`, then the following evaluates to `true`. ``` contains($input.MyInput.value, "fli") ``` Both expressions must evaluate to a string value. If either expression does not evaluate to a string value, then the result of the function is undefined. No conversions are performed. Bitwise Integer Manipulation Functions `bitor(expression1, expression2)` Evaluates the bitwise OR of the integer expressions (the binary OR operation is performed on the corresponding bits of the integers). For example, if input `MyInput` receives the message `{ "value1": 13, "value2": 5 }`, then the following evaluates to `13`. ``` bitor($input.MyInput.value1, $input.MyInput.value2) ``` Both expressions must evaluate to an integer value. If either expression does not evaluate to an integer value, then the result of the function is undefined. No conversions are performed. `bitand(expression1, expression2)` Evaluates the bitwise AND of the integer expressions (the binary AND operation is performed on the corresponding bits of the integers). For example, if input `MyInput` receives the message `{ "value1": 13, "value2": 5 }`, then the following evaluates to `5`. ``` bitand($input.MyInput.value1, $input.MyInput.value2) ``` Both expressions must evaluate to an integer value. If either expression does not evaluate to an integer value, then the result of the function is undefined. No conversions are performed. `bitxor(expression1, expression2)` Evaluates the bitwise XOR of the integer expressions (the binary XOR operation is performed on the corresponding bits of the integers). For example, if input `MyInput` receives the message `{ "value1": 13, "value2": 5 }`, then the following evaluates to `8`. ``` bitxor($input.MyInput.value1, $input.MyInput.value2) ``` Both expressions must evaluate to an integer value. If either expression does not evaluate to an integer value, then the result of the function is undefined. No conversions are performed. `bitnot(expression)` Evaluates the bitwise NOT of the integer expression (the binary NOT operation is performed on the bits of the integer). For example, if input `MyInput` receives the message `{ "value": 13 }`, then the following evaluates to `-14`. ``` bitnot($input.MyInput.value) ``` Both expressions must evaluate to an integer value. If either expression does not evaluate to an integer value, then the result of the function is undefined. No conversions are performed. ### AWS IoT Events reference for inputs and variables in expressions Reference for inputs and variables in expressions Inputs `$input.input-name.path-to-data` `input-name` is an input that you create using the [CreateInput](https://docs.aws.amazon.com/iotevents/latest/apireference/API_CreateInput.html) action. For example, if you have an input named `TemperatureInput` for which you defined `inputDefinition.attributes.jsonPath` entries, the values might appear in the following available fields. ``` { "temperature": 78.5, "date": "2018-10-03T16:09:09Z" } ``` To reference the value of the `temperature` field, use the following command. ``` $input.TemperatureInput.temperature ``` For fields whose values are arrays, you can reference members of the array using `[n]`. For example, given the following values: ``` { "temperatures": [ 78.4, 77.9, 78.8 ], "date": "2018-10-03T16:09:09Z" } ``` The value `78.8` can be referenced with the following command. ``` $input.TemperatureInput.temperatures[2] ``` Variables `$variable.variable-name` The `variable-name` is a variable that you defined using the [CreateDetectorModel](https://docs.aws.amazon.com/iotevents/latest/apireference/API_CreateDetectorModel.html) action. For example, if you have a variable named `TechnicianID` that you defined using `detectorDefinition.states.onInputEvents.actions.setVariable.variableName`, you can reference the (string) value most recently given to the variable with the following command. ``` $variable.TechnicianID ``` You can set the values of variables only using the `setVariable` action. You can't assign values for variables in an expression. A variable can't be unset. For example, you can't assign it the value `null`. **Note** In references that use identifiers that don't follow the (regular expression) pattern `[a-zA-Z][a-zA-Z0-9_]*`, you must enclose those identifiers in backticks (```). For example, a reference to an input named `MyInput` with a field named `_value` must specify this field as `$input.MyInput.`_value``. When you use references in expressions, check the following: + When you use a reference as an operand with one or more operators, make sure that all data types that you reference are compatible. For example, in the following expression, integer `2` is an operand of both the `==` and `&&` operators. To ensure that the operands are compatible, `$variable.testVariable + 1` and `$variable.testVariable` must reference an integer or decimal. In addition, integer `1` is an operand of the `+` operator. Therefore, `$variable.testVariable` must reference an integer or decimal. ``` ‘$variable.testVariable + 1 == 2 && $variable.testVariable’ ``` + When you use a reference as an argument passed to a function, make sure that the function supports the data types that you reference. For example, the following `timeout("time-name")` function requires a string with double quotes as the argument. If you use a reference for the *timer-name* value, you must reference a string with double quotes. ``` timeout("timer-name") ``` **Note** For the `convert(type, expression)` function, if you use a reference for the *type* value, the evaluated result of your reference must be `String`, `Decimal`, or `Boolean`. AWS IoT Events expressions support integer, decimal, string, and Boolean data types. The following table provides a list of incompatible pairs of types. | Incompatible pairs of types | | --- | | Integer, string | | Integer, Boolean | | Decimal, string | | Decimal, Boolean | | String, Boolean | ### Substitution templates for AWS IoT Events expressions Substitution templates **** `'${expression}'` The `${}` identifies the string as an interpolated string. The `expression` can be any AWS IoT Events expression. This includes operators, functions, and references. For example, you used the [SetVariableAction](https://docs.aws.amazon.com/iotevents/latest/apireference/API_SetVariableAction.html) action to define a variable. The `variableName` is `SensorID`, and the `value` is `10`. You can create the following substitution templates. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iotevents/latest/developerguide/iotevents-expressions.html) # Expression examples and usage for AWS IoT Events UsageExpression usage[https://docs.aws.amazon.com/iotevents/latest/developerguide/expression-usage.html](https://docs.aws.amazon.com/iotevents/latest/developerguide/expression-usage.html) Added examples to show you how to write expressions. You can specify values in a detector model in the following ways: + Enter supported expressions in the AWS IoT Events console. + Pass the expressions to the AWS IoT Events APIs as parameters. Expressions support literals, operators, functions, references, and substitution templates. **Important** Your expressions must reference a integer, decimal, string, or Boolean value. ## Writing AWS IoT Events expressions See the following examples to help you write your AWS IoT Events expressions: **Literal** For literal values, the expressions must contain single quotes. A Boolean value must be either `true` or `false`. ``` '123' # Integer '123.12' # Decimal 'hello' # String 'true' # Boolean ``` **Reference** For references, you must specify either variables or input values. + The following input references a decimal number, `10.01`. ``` $input.GreenhouseInput.temperature ``` + The following variable references a string, `Greenhouse Temperature Table`. ``` $variable.TableName ``` **Substitution template** For a substitution template, you must use `${}`, and the template must be in single quotes. A substitution template can also contain a combination of literals, operators, functions, references, and substitution templates. + The evaluated result of the following expression is a string, `50.018 in Fahrenheit`. ``` '${$input.GreenhouseInput.temperature * 9 / 5 + 32} in Fahrenheit' ``` + The evaluated result of the following expression is a string, `{\"sensor_id\":\"Sensor_1\",\"temperature\":\"50.018\"}`. ``` '{\"sensor_id\":\"${$input.GreenhouseInput.sensors[0].sensor1}\",\"temperature\":\"${$input.GreenhouseInput.temperature*9/5+32}\"}' ``` **String concatenation** For a string concatenation, you must use `+`. A string concatenation can also contain a combination of literals, operators, functions, references, and substitution templates. + The evaluated result of the following expression is a string, `Greenhouse Temperature Table 2000-01-01`. ``` 'Greenhouse Temperature Table ' + $input.GreenhouseInput.date ```