IoT Hub query language for device and module twins, jobs, and message routing

IoT Hub provides a powerful SQL-like language to retrieve information regarding device twins, module twins, jobs, and message routing. This article presents:

• En introduktion till de viktigaste egenskaperna hos IoT Hub-frågespråket.
• The detailed description of the language. Mer information om frågespråk för meddelanderoutning finns i Frågesyntax för IoT Hub-meddelanderoutning.

Specifika exempel finns i Frågor för IoT Hub-enheter och modultvillingar eller Frågor för IoT Hub-jobb.

Run IoT Hub queries

Du kan köra frågor mot ditt IoT-nav direkt i Azure-portalen.

1. Logga in på Azure-portalen och navigera till din IoT-hubb.
2. Välj Queries från sektionen Enhetshantering i navigationsmenyn.
3. Ange din fråga i textrutan och välj Run query.

Du kan också köra frågor inom dina applikationer med hjälp av Azure IoT tjänste-SDK:er och tjänste-API:er.

For example code implementing IoT Hub queries, see the Query examples with the service SDKs section.

Länkar till SDK-referenssidor och exempel finns i Azure IoT Hub SDK:er.

Basics of an IoT Hub query

Varje IoT Hub-fråga består av SELECT- och FROM-satser, med valfria WHERE- och GROUP BY-satser.

Queries are run on a collection of JSON documents, for example device twins. The FROM clause indicates the document collection to be iterated on (either devices, devices.modules, or devices.jobs).

Sedan tillämpas filtret i WHERE-satsen. With aggregations, the results of this step are grouped as specified in the GROUP BY clause. För varje grupp genereras en rad enligt vad som anges i SELECT-satsen.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

SELECT clause

SELECT <select_list>-satsen är obligatorisk i varje IoT Hub-fråga. It specifies what values are retrieved from the query. It specifies the JSON values to be used to generate new JSON objects. För varje element i den filtrerade (och eventuellt grupperade) delmängden av FROM-samlingen, genererar projektionsfasen ett nytt JSON-objekt. Detta objekt är konstruerat med de värden som anges i SELECT-satsen.

For example:

• Återställ alla värden

  SELECT *
  

• Returnera specifika egenskaper

  SELECT DeviceID, LastActivityTime
  

• Sammanställ resultaten av en fråga för att returnera ett antal

  SELECT COUNT() as TotalNumber
  

För närvarande stöds urvalsklausuler som skiljer sig från SELECT endast i aggregerade förfrågningar på enhetstvillingar.

Den följande syntaxen är grammatiken för SELECT-satsen:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name avser vilken egenskap som helst för JSON-dokumentet i FROM-samlingen.

FROM-sats

FROM <from_specification>-klasulen krävs i varje ioT Hub-fråga. Det måste vara ett av tre värden:

• enheter för att läsa av enhetstvillingar
• devices.modules för att fråga modultvillingar
• devices.jobs för att fråga efter jobbinformation per enhet

For example:

• Hämta alla enhetstvillingar

  SELECT * FROM devices
  

WHERE clause

WHERE <filter_condition>-satsen är valfri. Den anger ett eller flera villkor som JSON-dokumenten i FROM-samlingen måste uppfylla för att inkluderas som en del av resultatet. Any JSON document must evaluate the specified conditions to "true" to be included in the result.

For example:

• Retrieve all jobs that target a specific device

  SELECT * FROM devices.jobs
    WHERE devices.jobs.deviceId = 'myDeviceId'
  

De tillåtna villkoren beskrivs i avsnittet Uttryck och villkor .

GROUP BY clause

GROUP BY <group_specification>-klause är valfri. This clause executes after the filter specified in the WHERE clause, and before the projection specified in the SELECT. Den grupperar dokument baserat på värdet av ett attribut. These groups are used to generate aggregated values as specified in the SELECT clause.

For example:

• Return the count of devices that are reporting each telemetry configuration status

  SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status
  

För närvarande stöds endast GROUP BY-satsen när man frågar efter enheters tvillingar.

Den formella syntaxen för GROUP BY är:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name avser vilken egenskap som helst i JSON-dokumentet i FROM-samlingen.

Pagineringsresultat för sökfrågor

Ett frågeobjekt instansieras med en maxsidstorlek på mindre än eller lika med 100 poster. Om du vill hämta flera sidor anropar du nextAsTwin på Node.js SDK eller GetNextAsTwinAsync på .NET SDK-metoden flera gånger. A query object can expose multiple Next values, depending on the deserialization option required by the query. Till exempel kan ett frågeobjekt returnera enhetsdubblering eller jobbobjekt, eller ren JSON när man använder projektioner.

Uttryck och villkor

På en hög nivå, en expression:

• Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object).
• Is defined by manipulating data coming from the device JSON document and constants using built-in operators and functions.

Villkor är uttryck som utvärderas till ett booleskt värde. Varje konstant som skiljer sig från Boolesk true betraktas som false. Den här regeln inkluderar null, undefined, vilken som helst av objekt eller arrayinstans, vilken som helst sträng, och Booleanskt false.

The syntax for expressions is:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

To understand what each symbol in the expressions syntax stands for, refer to the following table:

Operators

The following operators are supported:

Functions

När man frågar efter tvillingar och jobb är den enda stödda funktionen:

I villkor för rutter stöds följande matematikfunktioner:

In routes conditions, the following type checking and casting functions are supported:

I villkoren för rutterna stöds följande strängfunktioner:

Frågeexempel med tjänstens SDK:er

C#-exempel

Frågefunktionen exponeras av Azure IoT Hub service SDK för .NET i klassen RegistryManager .

Here's an example of a simple query:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

Frågeobjektet instansieras med parametrarna som nämns i sidnumreringsavsnittet Frågeresultat . Flera sidor hämtas genom att anropa metoderna GetNextAsTwinAsync flera gånger.

Node.js example

Frågefunktionen exponeras av Azure IoT Hub-tjänst-SDK för Node.js i registry-objektet .

Here's an example of a simple query:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

Frågeobjektet instansieras med parametrarna som nämns i sidnumreringsavsnittet Frågeresultat . Multiple pages are retrieved by calling the nextAsTwin method multiple times.

Next steps

• Learn about routing messages based on message properties or message body with the IoT Hub message routing query syntax.
• Få specifika exempel på frågor för IoT Hub-enhets- och modultvillingar eller frågor för IoT Hub-jobb.