Een query uitvoeren op de Azure Digital Twins-tweelinggrafiek

  • Artikel

Dit artikel bevat queryvoorbeelden en instructies voor het gebruik van de Azure Digital Twins-querytaal om een query uit te voeren op uw tweelinggrafiek voor informatie. (Zie Querytaal voor een inleiding tot de 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 onder Verwijzing in de linkerinhoudsopgave voor de Documentatie van Azure Digital Twins. U kunt ook rechtstreeks naar de referentiesecties gaan via de onderstaande koppelingen:

Alle digitale dubbels weergeven

Dit is 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 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 met $, moet u escapen $ met een backslash om Cloud Shell te laten weten dat het geen variabele is en moet worden gebruikt als een letterlijke waarde in de querytekst.

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

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

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

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

U kunt ook tweelingen ophalen op basis van het type van een eigenschap. Hier volgt een query die tweelingen ophaalt waarvan Temperature de 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 toewijzingssleutels en -waarden rechtstreeks in de query gebruiken, zoals:

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 ([[<mapKey>]]) plaatsen om deze in de query te laten 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 dubbel.

Er wordt rekening gehouden met overname en modelversiebeheer en wordt geëvalueerd true voor een bepaalde tweeling als de dubbel aan een van deze voorwaarden voldoet:

  • De dubbel implementeert rechtstreeks het model dat is opgegeven aan IS_OF_MODEL()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 model uitbreidt dat is opgegeven aan IS_OF_MODEL()en het uitgebreide modelversienummer van de dubbel is groter dan of gelijk 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 tweelingen op basis van versie 4 of hoger van modellen die overnemen van widget.

IS_OF_MODEL kan verschillende parameters hebben en de rest van deze sectie is gewijd aan de verschillende overbelastingsopties.

Voor het eenvoudigste gebruik van IS_OF_MODEL is alleen een twinTypeName parameter nodig: IS_OF_MODEL(twinTypeName). Hier volgt een queryvoorbeeld waarin een waarde in deze parameter wordt doorgegeven:

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

Als u een tweelingverzameling wilt opgeven om te zoeken wanneer er meer dan één is (bijvoorbeeld wanneer een JOIN wordt gebruikt), voegt u de twinCollection parameter toe: IS_OF_MODEL(twinCollection, twinTypeName). Hier volgt een voorbeeld van een query 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 voorbeeld van een query 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 samen doorgeven: IS_OF_MODEL(twinCollection, twinTypeName, exact). Hier volgt een voorbeeld van een query 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-talen, is elke expressie in de FROM component geen tabel, maar wordt met de FROM component een cross-entity relationship traversal weergegeven. Voor het doorlopen van relaties gebruikt Azure Digital Twins een aangepaste versie van JOIN.

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

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

Eenvoudige relatiequery

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

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 een sleutelwaarde inline op te geven 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 structuur van de relatiequery 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 die de doeldubbels vindt van de feeds relaties die afkomstig zijn van de brondubbel-dubbel.

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 traceren om de brondubbel te vinden. Hier volgt een voorbeeld van een query waarmee de brondubbel van een feeds relatie met de doeldubbel 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.

Neem bijvoorbeeld een servicedBy relatie die een reportedCondition eigenschap heeft. In de onderstaande query krijgt deze relatie een alias van R om 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 van de servicedBy relatie zelf is (NIET van een digitale dubbel die een servicedBy relatie heeft).

Query's uitvoeren met meerdere JOIN's

Er worden maximaal vijf JOINs ondersteund in één query, zodat u meerdere niveaus van relaties tegelijk kunt doorlopen.

Als u een query 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 kamer 1 en 2 worden opgevraagd.

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 tellen met een toegepast filter op basis van het type dubbelmodel (zie Query's uitvoeren 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 lichtpanelen van de 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: retourset opgeven met projecties

Door projecties in de SELECT instructie te gebruiken, 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 projectie gebruikt om tweelingen en relaties te retourneren. De volgende query projecteert de consumer, factory en Edge vanuit een scenario waarin een factory met een id van 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 dubbel 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 deze 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 wordt de eigenschapsnamen gealiassen naar consumerName, first, seconden factoryArea.

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 projecteert als een tweeling.

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

Efficiënte query's maken met de OPERATOR IN

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

Denk bijvoorbeeld aan een scenario waarin gebouwen verdiepingen bevatten en verdiepingen ruimten bevatten. Als u wilt zoeken naar ruimten in een gebouw die dynamisch zijn, volgt u deze stappen.

  1. Vind vloeren in het gebouw op basis van de contains relatie.

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

  2. Als u ruimten wilt zoeken, kunt u in plaats van de verdiepingen een voor een te overwegen en een JOIN query uit te voeren om de ruimten voor elke kamer te vinden, query's 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 behulp van combinatieoperators om meer details in één query op te nemen. Hier volgen enkele andere voorbeelden van samengestelde query's die query's uitvoeren op meer dan één type dubbeldescriptor tegelijk.

  • Van de apparaten die Ruimte 123 heeft, retourneert u de MxChip-apparaten die de rol 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 met de naam Contains hebben met een andere tweeling met een id van id1
    SELECT Room
FROM DIGITALTWINS Room
JOIN Thermostat RELATED Room.Contains
WHERE Thermostat.$dtId = 'id1'
  • Alle kamers van dit kamermodel ophalen die zijn opgenomen in floor11
    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 te maken.

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 .NET -SDK-aanroep (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 wordt weergegeven 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 met 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>, <B>en <C>.
  • Andere indelingen van SELECT instructies kunnen worden gemaakt om aangepaste gegevens te retourneren. U kunt overwegen om uw eigen klassen te maken om aangepaste resultatensets te verwerken.

Query uitvoeren met paging

Query-aanroepen ondersteunen paging. Hier volgt een volledig voorbeeld van het gebruik van 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, met inbegrip van de Query-API die wordt gebruikt om de query's uit dit artikel uit te voeren.