Merge pull request #222675 from KennedyDMSFT/US44747-07

December freshness (7/11)

Author: prmerger-automator[bot]

articles/iot-hub/iot-hub-devguide-routing-query-syntax.md

@@ -5,22 +5,22 @@ author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 08/13/2018
+ms.date: 12/27/2022
 ms.author: kgremban
 ms.custom: ['Role: Cloud Development', 'Role: Data Analytics']
 ---
 
 # IoT Hub message routing query syntax
 
-Message routing enables users to route different data types, namely device telemetry messages, device lifecycle events, and device twin change events, to various endpoints. You can also apply rich queries to this data before routing it to receive the data that matters to you. This article describes the IoT Hub message routing query language, and provides some common query patterns.
+Message routing enables users to route different data types, including device telemetry messages, device lifecycle events, and device twin change events, to various endpoints. You can also apply rich queries to this data before routing it to receive the data that matters to you. This article describes the IoT Hub message routing query language, and provides some common query patterns.
 
 [!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-partial.md)]
 
-Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. If the message body is not JSON, message routing can still route the message, but queries cannot be applied to the message body.  Queries are described as Boolean expressions where a Boolean true makes the query succeed and route all the incoming data, and Boolean false fails the query and no data is routed. If the expression evaluates to null or undefined, it is treated as false and an error will be generated in IoT Hub [routes resource logs](monitor-iot-hub-reference.md#routes). The query syntax must be correct for the route to be saved and evaluated.  
+Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. If the message body isn't in JavaScript Object Notation (JSON) format, message routing can still route the message, but queries can't be applied to the message body.  Queries are described as Boolean expressions where, if true, the query succeeds and routes all the incoming data; otherwise, the query fails and the incoming data isn't routed. If the expression evaluates to a null or undefined value, it's treated as a Boolean false value and an error is generated in IoT Hub [routes resource logs](monitor-iot-hub-reference.md#routes). The query syntax must be correct for the route to be saved and evaluated.  
 
 ## Message routing query based on message properties
 
-IoT Hub defines a [common format](iot-hub-devguide-messages-construct.md) for all device-to-cloud messaging for interoperability across protocols. IoT Hub assumes the following JSON representation of the message. System properties are added for all users and identify content of the message. Users can selectively add application properties to the message. We recommend using unique property names as IoT Hub device-to-cloud messaging is not case-sensitive. For example, if you have multiple properties with the same name, IoT Hub will only send one of the properties.  
+IoT Hub defines a [common format](iot-hub-devguide-messages-construct.md) for all device-to-cloud messaging for interoperability across protocols. IoT Hub assumes the following JSON representation of the message. System properties are added for all users and identify content of the message. Users can selectively add application properties to the message. We recommend using unique property names because IoT Hub device-to-cloud messaging isn't case-sensitive. For example, if you have multiple properties with the same name, IoT Hub will only send one of the properties.  
 
 ```json
 { 
@@ -44,35 +44,35 @@ IoT Hub defines a [common format](iot-hub-devguide-messages-construct.md) for al
 
 ### System properties
 
-System properties help identify the contents and source of the messages.
+System properties help identify the contents and source of the messages, some of which are described in the following table.
 
 | Property | Type | Description |
 | -------- | ---- | ----------- |
 | contentType | string | The user specifies the content type of the message. To allow querying on the message body, this value should be set to `application/JSON`. |
-| contentEncoding | string | The user specifies the encoding type of the message. Allowed values are `UTF-8`, `UTF-16`, and `UTF-32` if the contentType is set to application/JSON. |
+| contentEncoding | string | The user specifies the encoding type of the message. Allowed values are `UTF-8`, `UTF-16`, and `UTF-32` if the contentType property is set to `application/JSON`. |
 | iothub-connection-device-id | string | This value is set by IoT Hub and identifies the ID of the device. To query, use `$connectionDeviceId`. |
 | iothub-connection-module-id | string | This value is set by IoT Hub and identifies the ID of the edge module. To query, use `$connectionModuleId`. |
-| iothub-enqueuedtime | string | This value is set by IoT Hub and represents the actual time of enqueuing the message in UTC. To query, use `enqueuedTime`. |
+| iothub-enqueuedtime | string | This value is set by IoT Hub and represents the actual time of enqueuing the message in UTC. To query, use `$enqueuedTime`. |
 | dt-dataschema | string |  This value is set by IoT Hub on device-to-cloud messages. It contains the device model ID set in the device connection. To query, use `$dt-dataschema`. |
 | dt-subject | string | The name of the component that is sending the device-to-cloud messages. To query, use `$dt-subject`. |
 
-As described in [Create and read IoT Hub messages](iot-hub-devguide-messages-construct.md), there are additional system properties in a message. In addition to above properties in the previous table, you can also query **connectionDeviceId**, **connectionModuleId**.
+The previous table describes only some of the system properties available in a message. For more information about the other available system properties, see [Create and read IoT Hub messages](iot-hub-devguide-messages-construct.md). 
 
 ### Application properties
 
 Application properties are user-defined strings that can be added to the message. These fields are optional.  
 
 ### Query expressions
 
-A query on message system properties needs to be prefixed with the `$` symbol. Queries on application properties are accessed with their name and should not be prefixed with the `$`symbol. If an application property name begins with `$`, then IoT Hub will search for it in the system properties, and it is not found, then it will look in the application properties. For example: 
+A query on message system properties must be prefixed with the `$` symbol. Queries on application properties are accessed with their name and shouldn't be prefixed with the `$`symbol. If an application property name begins with `$`, then IoT Hub first searches for it in the system properties, and if it's not found will then search for it in the application properties. The following examples show how to query on system properties and application properties.
 
-To query on system property contentEncoding 
+To query on the system property contentEncoding:
 
 ```sql
 $contentEncoding = 'UTF-8'
 ```
 
-To query on application property processingPath:
+To query on the application property processingPath:
 
 ```sql
 processingPath = 'hot'
@@ -84,11 +84,11 @@ To combine these queries, you can use Boolean expressions and functions:
 $contentEncoding = 'UTF-8' AND processingPath = 'hot'
 ```
 
-A full list of supported operators and functions is shown in [Expression and conditions](iot-hub-devguide-query-language.md#expressions-and-conditions).
+A full list of supported operators and functions is provided in the [Expression and conditions](iot-hub-devguide-query-language.md#expressions-and-conditions) section of [IoT Hub query language for device and module twins, jobs, and message routing](iot-hub-devguide-query-language.md).
 
 ## Message routing query based on message body
 
-To enable querying on message body, the message should be in a JSON encoded in either UTF-8, UTF-16 or UTF-32. The `contentType` must be set to `application/JSON` and `contentEncoding` to one of the supported UTF encodings in the system property. If these properties are not specified, IoT Hub will not evaluate the query expression on the message body. 
+To enable querying on a message body, the message should be in a JSON format and encoded in either UTF-8, UTF-16 or UTF-32. The `contentType` system property must be set to `application/JSON`. The `contentEncoding` system property must be set to one of the UTF encoding values supported by that system property. If these system properties aren't specified, IoT Hub won't evaluate the query expression on the message body. 
 
 The following example shows how to create a message with a properly formed and encoded JSON body: 
 
@@ -140,11 +140,11 @@ deviceClient.sendEvent(message, (err, res) => {
 ```
 
 > [!NOTE] 
-> This shows how to handle the encoding of the body in JavaScript. If you want to see a sample in C#, download the [Azure IoT C# SDK](https://github.com/Azure/azure-iot-sdk-csharp/archive/main.zip). Unzip the master.zip file. The Visual Studio solution *SimulatedDevice*'s Program.cs file shows how to encode and submit messages to an IoT Hub. This is the same sample used for testing the message routing, as explained in the [Message Routing tutorial](tutorial-routing.md). At the bottom of Program.cs, it also has a method to read in one of the encoded files, decode it, and write it back out as ASCII so you can read it. 
+> This shows how to handle the encoding of the message body in JavaScript. If you want to see a sample in C#, download the [Microsoft Azure IoT SDK for .NET](https://github.com/Azure/azure-iot-sdk-csharp/archive/main.zip), and then expand the compressed folder (azure-iot-sdk-csharp-main.zip). The Program.cs file for the *HubRoutingSample* device sample, in the *\iothub\device\samples\how to guides\HubRoutingSample* subfolder of the SDK, shows how to encode and submit messages to an IoT hub. This is the same sample used for testing the message routing, as explained in the [Message Routing tutorial](tutorial-routing.md). The Program.cs file also has a method named `ReadOneRowFromFile`, which reads one of the encoded files, decodes it, and writes it back out as ASCII so you can read it. 
 
 ### Query expressions
 
-A query on a message body needs to be prefixed with `$body`. You can use a body reference, body array reference, or multiple body references in the query expression. Your query expression can also combine a body reference with message system properties, and message application properties reference. For example, the following are all valid query expressions:
+A query on a message body needs to be prefixed with `$body`. You can use a body reference, body array reference, or multiple body references in the query expression. Your query expression can also combine a body reference with a message system properties reference or a message application properties reference. For example, the following examples are all valid query expressions:
 
 ```sql
 $body.Weather.HistoricalData[0].Month = 'Feb' 
@@ -163,7 +163,7 @@ $body.Weather.Temperature = 50 AND processingPath = 'hot'
 ```
 
 > [!NOTE]
-> To filter a twin notification payload based on what changed, run your query on the message body. For example, to filter when there is a desire property change on `sendFrequency` and the value is bigger than 10:
+> To filter a twin notification payload based on what changed, run your query on the message body. For example, to filter when there is a desired property change on `sendFrequency` and the value is greater than 10:
 >
 > ```sql
 > $body.properties.desired.telemetryConfig.sendFrequency > 10
@@ -175,15 +175,15 @@ $body.Weather.Temperature = 50 AND processingPath = 'hot'
 > ```
 
 > [!NOTE]
-> You can run queries and functions only on properties in the body reference. You can't run queries or functions on the entire body reference. For example, the following query is *not* supported and will return `undefined`:
+> You can run queries and functions only on properties in the body reference. You can't run queries or functions on the entire body reference. For example, the following query is *not* supported and returns `undefined`:
 >
 > ```sql
 > $body[0] = 'Feb'
 > ```
 
 ## Message routing query based on device twin 
 
-Message routing enables you to query on [Device Twin](iot-hub-devguide-device-twins.md) tags and properties, which are JSON objects. Querying on module twin is also supported. A sample of Device Twin tags and properties is shown below.
+Message routing enables you to query on [Device Twin](iot-hub-devguide-device-twins.md) tags and properties, which are JSON objects. Querying on module twin is also supported. The following sample illustrates a query on device twin tags and properties.
 
 ```JSON
 {
@@ -215,11 +215,11 @@ Message routing enables you to query on [Device Twin](iot-hub-devguide-device-tw
 ```
 
 > [!NOTE]
-> Modules do not inherit twin tags from their corresponding devices. Twin queries for messages originating from device modules (for example from IoT Edge modules) query against the module twin and not the corresponding device twin.
+> Modules do not inherit twin tags from their corresponding devices. Twin queries for messages originating from device modules (for example, from IoT Edge modules) query against the module twin and not the corresponding device twin.
 
 ### Query expressions
 
-A query on a device or module twin needs to be prefixed with `$twin`. Your query expression can also combine a twin tag or property reference with a body reference, a message system properties reference, and/or a message application properties reference. We recommend using unique names in tags and properties as the query is not case-sensitive. This applies to both device twins and module twins. Also refrain from using `twin`, `$twin`, `body`, or `$body`, as a property names. For example, the following are all valid query expressions: 
+A query on a device twin or module twin needs to be prefixed with `$twin`. Your query expression can also combine a twin tag or property reference with a body reference, a message system properties reference, or a message application properties reference. We recommend using unique names in tags and properties because the query isn't case-sensitive. This recommendation applies to both device twins and module twins. We also recommend that you avoid using `twin`, `$twin`, `body`, or `$body` as property names. For example, the following examples are all valid query expressions: 
 
 ```sql
 $twin.properties.desired.telemetryConfig.sendFrequency = '5m'