Een query uitvoeren op de Azure Digital Twins-tweelinggrafiek

Artikel
02/04/2025

Dit artikel bevat queryvoorbeelden en instructies voor het gebruik van de Azure Digital Twins-querytaal om een query uit te voeren op uw dubbelgrafiek voor informatie. (Zie voor een inleiding tot de querytaal Querytaal.)

Het artikel bevat voorbeeldquery's die de structuur van de querytaal en algemene querybewerkingen voor digitale dubbels illustreren. Ook wordt beschreven hoe u uw query's uitvoert nadat u ze hebt geschreven, met behulp van de Azure Digital Twins Query-API of een SDK.

Notitie

Als u de onderstaande voorbeeldquery's uitvoert met een API- of SDK-aanroep, moet u de querytekst in één regel samenvatten.

Referentiedocumentatie

De naslaginformatie over de querytaal vindt u in de linkeropgave van de inhoudsopgave voor de Documentatie van Azure Digital Twins. U kunt ook rechtstreeks naar de referentiesecties gaan met behulp van de onderstaande koppelingen:

Clausules
- SELECT
- VAN
- LUCIFER
- VERBINDEN
- WAAR
Functies
Operators
Gereserveerde trefwoorden

Alle digitale dubbels weergeven

Hier volgt de basisquery die een lijst met alle digitale dubbels in het exemplaar retourneert:

SELECT * FROM DIGITALTWINS

Query uitvoeren op eigenschap

Digitale dubbels ophalen op basis van eigenschappen (inclusief id en metagegevens):

SELECT  *
FROM DIGITALTWINS T  
WHERE T.firmwareVersion = '1.1'
AND T.$dtId in ['123', '456']
AND T.Temperature = 70

Zoals wordt weergegeven in de bovenstaande query, wordt de id van een digitale dubbel opgevraagd met behulp van het metagegevensveld $dtId.

Tip

Als u Cloud Shell gebruikt om een query uit te voeren met metagegevensvelden die beginnen $, moet u een $ backslash gebruiken om Cloud Shell te laten weten dat het geen variabele is en als letterlijke gegevens in de querytekst moet worden gebruikt.

U kunt ook tweelingen ophalen op basis van of een bepaalde eigenschap is gedefinieerd. Hier volgt een query waarmee tweelingen worden ophaalt die een gedefinieerde Location eigenschap hebben:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Met deze query kunt u dubbels ophalen op basis van hun tag eigenschappen, zoals beschreven in Tags toevoegen aan digitale dubbels. Hier volgt een query waarmee alle dubbels worden getagd met red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

U kunt ook tweelingen ophalen op basis van het type eigenschap. Hier volgt een query die tweelingen ophaalt waarvan de Temperature eigenschap een getal is:

SELECT * FROM DIGITALTWINS T WHERE IS_NUMBER(T.Temperature)

Eigenschappen van querytoewijzing

Als een eigenschap van het complexe type Mapis, kunt u de kaartsleutels en -waarden rechtstreeks in de query gebruiken, zoals deze:

SELECT * FROM DIGITALTWINS T WHERE T.<propertyName>.<mapKey> = '<mapValue>'

Als de kaartsleutel begint met een numeriek teken, moet u de sleutel tussen dubbele vierkante haken laten teruglopen ([[<mapKey>]]) om deze in de query te ontsnappen, vergelijkbaar met de strategie voor het uitvoeren van query's met gereserveerde trefwoorden.

Query's uitvoeren op model

De IS_OF_MODEL operator kan worden gebruikt om te filteren op basis van het model van de tweeling.

Het beschouwt overname- en modelversiebeheer en evalueert naar true een bepaalde dubbel als de dubbel aan een van deze voorwaarden voldoet:

De dubbel implementeert het opgegeven IS_OF_MODEL()model rechtstreeks en het versienummer van het model op de dubbel is groter dan of gelijk aan het versienummer van het opgegeven model
De dubbel implementeert een model dat het opgegeven IS_OF_MODEL()model uitbreidt en het uitgebreide modelversienummer van de dubbel groter is dan of gelijk is aan het versienummer van het opgegeven model

Als u bijvoorbeeld een query uitvoert op tweelingen van het model dtmi:example:widget;4, retourneert de query alle tweelingen op basis van versie 4 of hoger van het widgetmodel en ook dubbels op basis van versie 4 of hoger van alle modellen die overnemen van widget.

IS_OF_MODEL kan verschillende parameters gebruiken en de rest van deze sectie is toegewezen aan de verschillende overbelastingsopties.

Het eenvoudigste gebruik van IS_OF_MODEL gebruikt slechts een twinTypeName parameter: IS_OF_MODEL(twinTypeName). Hier volgt een queryvoorbeeld waarmee een waarde in deze parameter wordt doorgegeven:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1')

Als u een verzameling dubbels wilt opgeven om te zoeken wanneer er meer dan één is (zoals wanneer een JOIN wordt gebruikt), voegt u de twinCollection parameter toe: IS_OF_MODEL(twinCollection, twinTypeName) Hier volgt een queryvoorbeeld waarmee een waarde voor deze parameter wordt toegevoegd:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1')

Als u een exacte overeenkomst wilt uitvoeren, voegt u de exact parameter toe: IS_OF_MODEL(twinTypeName, exact). Hier volgt een queryvoorbeeld waarmee een waarde voor deze parameter wordt toegevoegd:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1', exact)

U kunt ook alle drie de argumenten bij elkaar doorgeven: IS_OF_MODEL(twinCollection, twinTypeName, exact). Hier volgt een queryvoorbeeld waarin een waarde wordt opgegeven voor alle drie de parameters:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1', exact)

Query's uitvoeren op relatie

Bij het uitvoeren van query's op basis van relaties van digitale dubbels heeft de Azure Digital Twins-querytaal een speciale syntaxis.

Relaties worden in het querybereik gehaald in de FROM-component. In tegenstelling tot in 'klassieke' SQL-typetalen is elke expressie in de FROM component geen tabel; in plaats daarvan geeft de FROM component een doorkruising van relaties tussen entiteiten weer. Azure Digital Twins maakt gebruik van een aangepaste versie van JOIN.

Zoals u weet, bestaan er met de mogelijkheden van het Azure Digital Twins-model niet onafhankelijk van tweelingen, wat betekent dat er geen onafhankelijk query's kunnen worden uitgevoerd op relaties en moeten ze zijn gekoppeld aan een dubbel. Om dit feit weer te geven, wordt het trefwoord RELATED gebruikt in de JOIN component om de set van een bepaald type relatie op te halen die afkomstig is van de tweelingverzameling. De query moet vervolgens in de WHERE component filteren om aan te geven welke specifieke tweeling(en) moeten worden gebruikt in de relatiequery (met behulp van de waarden van $dtId de tweeling).

In de volgende secties ziet u voorbeelden van hoe dit eruitziet.

Basisrelatiequery

Hier volgt een voorbeeldquery op basis van een relatie. Dit codefragment selecteert alle digitale dubbels met een ID eigenschap van ABC, en alle digitale dubbels die zijn gerelateerd aan deze digitale dubbels via een contains relatie.

SELECT T, CT
FROM DIGITALTWINS T
JOIN CT RELATED T.contains
WHERE T.$dtId = 'ABC'

Het type relatie (contains in het bovenstaande voorbeeld) wordt aangegeven met behulp van het veld van name de relatie uit de DTDL-definitie.

Notitie

De ontwikkelaar hoeft dit JOIN niet te correleren met een sleutelwaarde in de WHERE component (of geef een sleutelwaarde inline op met de JOIN definitie). Deze correlatie wordt automatisch berekend door het systeem, omdat de relatie-eigenschappen zelf de doelentiteit aanduiden.

Query's uitvoeren op de bron of het doel van een relatie

U kunt de relatiequerystructuur gebruiken om een digitale dubbel te identificeren die de bron of het doel van een relatie is.

U kunt bijvoorbeeld beginnen met een brondubbel en de bijbehorende relaties volgen om de doeldubbels van de relaties te vinden. Hier volgt een voorbeeld van een query waarmee de doeldubbels van de feeds relaties worden gevonden die afkomstig zijn van de brondubbel.

SELECT target 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE source.$dtId = 'source-twin'

U kunt ook beginnen met het doel van de relatie en de relatie terug traceren om de brondubbel te vinden. Hier volgt een voorbeeld van een query waarmee de brondubbel van een feeds relatie met de doeldubbel van de tweeling wordt gevonden.

SELECT source 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE target.$dtId = 'target-twin'

Een query uitvoeren op de eigenschappen van een relatie

Net zoals digitale dubbels over eigenschappen beschikken die via DTDL zijn beschreven, kunnen relaties ook over eigenschappen beschikken. U kunt query's uitvoeren op dubbels op basis van de eigenschappen van hun relaties. Met de Azure Digital Twins-querytaal kunt u relaties filteren en projecteren door een alias toe te wijzen aan de relatie binnen de JOIN component.

Denk bijvoorbeeld aan een servicedBy relatie met een reportedCondition eigenschap. In de onderstaande query krijgt deze relatie een alias om R te verwijzen naar de eigenschap.

SELECT T, SBT, R
FROM DIGITALTWINS T
JOIN SBT RELATED T.servicedBy R
WHERE T.$dtId = 'ABC'
AND R.reportedCondition = 'clean'

In het bovenstaande voorbeeld ziet u hoe reportedCondition een eigenschap is van de servicedBy relatie zelf (NIET van een digitale dubbel die een servicedBy relatie heeft).

Query's uitvoeren met meerdere JOI's

Maximaal vijf JOINs worden ondersteund in één query, waarmee u meerdere niveaus van relaties tegelijk kunt doorlopen.

Als u query's wilt uitvoeren op meerdere niveaus van relaties, gebruikt u één FROM instructie gevolgd door N-instructies JOIN , waarbij de JOIN instructies relaties uitdrukken op het resultaat van een vorige FROM of JOIN instructie.

Hier volgt een voorbeeld van een multi-join-query, waarmee alle gloeilampen in de lichtpanelen in ruimten 1 en 2 worden weergegeven.

SELECT LightBulb
FROM DIGITALTWINS Room
JOIN LightPanel RELATED Room.contains
JOIN LightBulb RELATED LightPanel.contains
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb ;1')
AND Room.$dtId IN ['room1', 'room2']

Items tellen

U kunt het aantal items in een resultatenset tellen met behulp van de Select COUNT component:

SELECT COUNT()
FROM DIGITALTWINS

Voeg een WHERE component toe om het aantal items te tellen dat aan een bepaald criterium voldoet. Hier volgen enkele voorbeelden van het tellen met een toegepast filter op basis van het type dubbelmodel (zie Query op model hieronder voor meer informatie over deze syntaxis):

SELECT COUNT()
FROM DIGITALTWINS
WHERE IS_OF_MODEL('dtmi:sample:Room;1')

SELECT COUNT()
FROM DIGITALTWINS c
WHERE IS_OF_MODEL('dtmi:sample:Room;1') AND c.Capacity > 20

U kunt ook samen met de JOIN component gebruikenCOUNT. Hier volgt een query waarmee alle gloeilampen in de lichte panelen van ruimten 1 en 2 worden geteld:

SELECT COUNT()  
FROM DIGITALTWINS Room  
JOIN LightPanel RELATED Room.contains  
JOIN LightBulb RELATED LightPanel.contains  
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')  
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb;1')  
AND Room.$dtId IN ['room1', 'room2']

Resultaten filteren: topitems selecteren

U kunt de verschillende 'top'-items in een query selecteren met behulp van de Select TOP component.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Resultaten filteren: geef een geretourneerde set op met projecties

Met behulp van projecties in de SELECT instructie kunt u kiezen welke kolommen een query retourneert. Projectie wordt nu ondersteund voor zowel primitieve als complexe eigenschappen. Zie de referentiedocumentatie voor select-componenten voor meer informatie over projecties met Azure Digital Twins.

Hier volgt een voorbeeld van een query die gebruikmaakt van projectie om tweelingen en relaties te retourneren. De volgende query projecteert de Consument, Factory en Edge vanuit een scenario waarin een factory met een id ABC is gerelateerd aan de consument via een relatie van Factory.customer, en die relatie wordt weergegeven als de Edge.

SELECT Consumer, Factory, Edge
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

U kunt projectie ook gebruiken om een eigenschap van een tweeling te retourneren. De volgende query projecteert de Name eigenschap van de consumenten die zijn gerelateerd aan de factory met een id van ABC via een relatie van Factory.customer.

SELECT Consumer.name
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

U kunt projectie ook gebruiken om een eigenschap van een relatie te retourneren. Net als in het vorige voorbeeld projecteert de volgende query de Name eigenschap van de consumenten die zijn gerelateerd aan de factory met een id van ABC via een relatie van Factory.customer; maar nu retourneert het ook twee eigenschappen van die relatie, prop1 en prop2. Dit doet u door de relatie Edge een naam te geven en de eigenschappen ervan te verzamelen.

SELECT Consumer.name, Edge.prop1, Edge.prop2, Factory.area
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

U kunt ook aliassen gebruiken om query's met projectie te vereenvoudigen.

Met de volgende query worden dezelfde bewerkingen uitgevoerd als in het vorige voorbeeld, maar worden de eigenschapsnamen in consumerNamefirst, en .factoryAreasecond

SELECT Consumer.name AS consumerName, Edge.prop1 AS first, Edge.prop2 AS second, Factory.area AS factoryArea
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Hier volgt een vergelijkbare query die dezelfde set als hierboven opvraagt, maar alleen de Consumer.name eigenschap projecteert als consumerNameen de volledige factory als dubbel projecteert.

SELECT Consumer.name AS consumerName, Factory
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Efficiënte query's bouwen met de IN-operator

U kunt het aantal query's dat u nodig hebt aanzienlijk verminderen door een matrix met dubbels te bouwen en query's uit te voeren met de IN operator.

Denk bijvoorbeeld aan een scenario waarin gebouwen verdiepingen en verdiepingen bevatten. Als u wilt zoeken naar ruimten in een gebouw dat warm is, kunt u deze stappen volgen.

Vind verdiepingen in het gebouw op basis van de contains relatie.

SELECT Floor
FROM DIGITALTWINS Building
JOIN Floor RELATED Building.contains
WHERE Building.$dtId = @buildingId

Als u kamers wilt zoeken, kunt u in plaats van de verdiepingen één voor één te overwegen en een JOIN query uit te voeren om de ruimten voor elke ruimte te vinden, een query uitvoeren met een verzameling van de verdiepingen in het gebouw (met de naam Floor in de onderstaande query).

In client-app:
```
var floors = "['floor1','floor2', ..'floorn']"; 
```
In query:
```
SELECT Room
FROM DIGITALTWINS Floor
JOIN Room RELATED Floor.contains
WHERE Floor.$dtId IN ['floor1','floor2', ..'floorn']
AND Room. Temperature > 72
AND IS_OF_MODEL(Room, 'dtmi:com:contoso:Room;1')
```

Andere voorbeelden van samengestelde query's

U kunt een van de bovenstaande typen query's combineren met combinatieoperators om meer details in één query op te nemen. Hier volgen enkele andere voorbeelden van samengestelde query's die tegelijk query's uitvoeren op meer dan één type dubbeldescriptor.

Uit de apparaten die Room 123 heeft, retourneert u de MxChip-apparaten die de rol van Operator dienen

SELECT device
FROM DIGITALTWINS space
JOIN device RELATED space.has
WHERE space.$dtid = 'Room 123'
AND device.$metadata.model = 'dtmi:contoso:com:DigitalTwins:MxChip:3'
AND has.role = 'Operator'

Tweelingen ophalen die een relatie hebben met Contains een andere tweeling met een id van id1

SELECT Room
FROM DIGITALTWINS Room
JOIN Thermostat RELATED Room.Contains
WHERE Thermostat.$dtId = 'id1'

Haal alle kamers van dit kamermodel op dat is opgenomen in verdieping11

SELECT Room
FROM DIGITALTWINS Floor
JOIN Room RELATED Floor.Contains
WHERE Floor.$dtId = 'floor11'
AND IS_OF_MODEL(Room, 'dtmi:contoso:com:DigitalTwins:Room;1')

Query's uitvoeren met de API

Zodra u een queryreeks hebt gekozen, voert u deze uit door een aanroep naar de Query-API uit te voeren.

U kunt de API rechtstreeks aanroepen of een van de SDK's gebruiken die beschikbaar zijn voor Azure Digital Twins.

Het volgende codefragment illustreert de SDK-aanroep van .NET (C#) vanuit een client-app:

// Run a query for all twins   
string query = "SELECT * FROM DIGITALTWINS";
AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>(query);

De query die in deze aanroep wordt gebruikt, retourneert een lijst met digitale dubbels, die in het bovenstaande voorbeeld worden aangeduid met BasicDigitalTwin-objecten . Het retourtype van uw gegevens voor elke query is afhankelijk van de termen die u opgeeft met de SELECT instructie:

Query's die beginnen, SELECT * FROM ... retourneren een lijst met digitale dubbels (die kunnen worden geserialiseerd als BasicDigitalTwin objecten of andere aangepaste typen digitale dubbels die u mogelijk hebt gemaakt).
Query's die in de indeling SELECT <A>, <B>, <C> FROM ... beginnen, retourneren een woordenlijst met sleutels <A>en <C><B>.
Andere indelingen van SELECT instructies kunnen worden gemaakt om aangepaste gegevens te retourneren. U kunt overwegen om uw eigen klassen te maken voor het afhandelen van aangepaste resultatensets.

Query met paging

Queryoproepen ondersteunen paging. Hier volgt een volledig voorbeeld van het gebruik BasicDigitalTwin als queryresultaattype met foutafhandeling en paging:

AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>("Select * From DigitalTwins");
try
{
    await foreach (BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

Volgende stappen

Meer informatie over de Azure Digital Twins-API's en SDK's, waaronder de query-API die wordt gebruikt om de query's uit te voeren vanuit dit artikel.

Delen via