Fråga Azure Digital Twins-tvillingdiagrammet

Den här artikeln innehåller frågeexempel och instruktioner för hur du använder Azure Digital Twins-frågespråket för att fråga tvillingdiagrammet om du vill ha information. (En introduktion till frågespråket finns i Frågespråk.)

Artikeln innehåller exempelfrågor som illustrerar frågespråkstrukturen och vanliga frågeåtgärder för digitala tvillingar. Den beskriver också hur du kör dina frågor när du har skrivit dem med hjälp av Azure Digital Twins Query API eller en SDK.

Anteckning

Om du kör exempelfrågorna nedan med ett API- eller SDK-anrop måste du komprimera frågetexten till en enda rad.

Referensdokumentation

Referensen för frågespråk finns under Referens i den vänstra innehållsförteckningen för Azure Digital Twins-dokumentationen. Du kan också gå direkt till referensavsnitten med hjälp av länkarna nedan:

• Satser
  • SELECT
  • FRÅN
  • MATCHA
  • Ansluta sig till
  • DÄR
• Funktioner
• Operatorer
• Reserverade nyckelord

Visa alla digitala tvillingar

Här är den grundläggande frågan som returnerar en lista över alla digitala tvillingar i instansen:

SELECT * FROM DIGITALTWINS

Fråga efter egenskap

Hämta digitala tvillingar efter egenskaper (inklusive ID och metadata):

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

Som du ser i frågan ovan efterfrågas ID:t för en digital tvilling med hjälp av metadatafältet $dtId.

Tips

Om du använder Cloud Shell för att köra en fråga med metadatafält som börjar med $bör du undvika $ med ett omvänt snedstreck för att låta Cloud Shell veta att det inte är en variabel och bör användas som en literal i frågetexten.

Du kan också hämta tvillingar baserat på om en viss egenskap har definierats. Här är en fråga som hämtar tvillingar som har en definierad Location egenskap:

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Den här frågan kan hjälpa dig att få tvillingar efter deras tag egenskaper, enligt beskrivningen i Lägg till taggar i digitala tvillingar. Här är en fråga som hämtar alla tvillingar taggade med red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Du kan också hämta tvillingar baserat på typen av en egenskap. Här är en fråga som hämtar tvillingar vars Temperature egenskap är ett tal:

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

Egenskaper för frågekarta

Om en egenskap är av den komplexa typen Mapkan du använda kartnycklarna och värdena direkt i frågan, så här:

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

Om kartnyckeln börjar med ett numeriskt tecken måste du omsluta nyckeln med dubbla hakparenteser ([[<mapKey>]]) för att undkomma den i frågan, ungefär som strategin för att fråga med reserverade nyckelord.

Fråga efter modell

Operatorn IS_OF_MODEL kan användas för att filtrera baserat på tvillingens modell.

Den tar hänsyn till arvs - och modellversionshantering och utvärderas till true för en viss tvilling om tvillingen uppfyller något av följande villkor:

• Tvillingen implementerar direkt modellen som tillhandahålls till IS_OF_MODEL()och versionsnumret för modellen på tvillingen är större än eller lika med versionsnumret för den angivna modellen
• Tvillingen implementerar en modell som utökar modellen till IS_OF_MODEL(), och tvillingens utökade modellversionsnummer är större än eller lika med versionsnumret för den angivna modellen

Om du till exempel frågar efter tvillingar i modellen dtmi:example:widget;4returnerar frågan alla tvillingar baserat på version 4 eller senare av widgetmodellen och även tvillingar baserat på version 4 eller senare av alla modeller som ärver från widgeten.

IS_OF_MODEL kan ta flera olika parametrar och resten av det här avsnittet är dedikerat till sina olika överlagringsalternativ.

Den enklaste användningen av IS_OF_MODEL tar bara en twinTypeName parameter: IS_OF_MODEL(twinTypeName). Här är ett frågeexempel som skickar ett värde i den här parametern:

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

Om du vill ange en tvillingsamling att söka efter när det finns fler än en (till exempel när en JOIN används) lägger du till parametern twinCollection : IS_OF_MODEL(twinCollection, twinTypeName). Här är ett frågeexempel som lägger till ett värde för den här parametern:

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

Om du vill göra en exakt matchning lägger du till parametern exact : IS_OF_MODEL(twinTypeName, exact). Här är ett frågeexempel som lägger till ett värde för den här parametern:

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

Du kan också skicka alla tre argumenten tillsammans: IS_OF_MODEL(twinCollection, twinTypeName, exact). Här är ett frågeexempel som anger ett värde för alla tre parametrarna:

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

Fråga efter relation

När du kör frågor baserat på digitala tvillingars relationer har Azure Digital Twins-frågespråket en speciell syntax.

Relationer hämtas in i frågeomfånget i FROM-satsen. Till skillnad från i "klassiska" SQL-språk är varje uttryck i FROM -satsen inte en tabell, FROM utan satsen uttrycker en korsentitetsrelationsbläddering. För att bläddra mellan relationer använder Azure Digital Twins en anpassad version av JOIN.

Kom ihåg att med Azure Digital Twins-modellfunktionerna finns inte relationer oberoende av tvillingar, vilket innebär att relationer här inte kan efterfrågas oberoende av varandra och måste vara knutna till en tvilling. För att återspegla detta används nyckelordet RELATEDJOIN i -satsen för att hämta en uppsättning av en viss typ av relation som kommer från tvillingsamlingen. Frågan måste sedan filtrera i WHERE -satsen för att ange vilka specifika tvillingar som ska användas i relationsfrågan (med hjälp av tvillingarnas $dtId värden).

Följande avsnitt innehåller exempel på hur detta ser ut.

Grundläggande relationsfråga

Här är en exempelrelationsbaserad fråga. Det här kodfragmentet väljer alla digitala tvillingar med egenskapen IDABC, och alla digitala tvillingar som är relaterade till dessa digitala tvillingar via en contains relation.

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

Typen av relation (contains i exemplet ovan) anges med hjälp av relationens name fält från dess DTDL-definition.

Anteckning

Utvecklaren behöver inte korrelera detta JOIN med ett nyckelvärde i WHERE -satsen (eller ange ett nyckelvärde infogat med JOIN definitionen). Den här korrelationen beräknas automatiskt av systemet, eftersom relationsegenskaperna själva identifierar målentiteten.

Fråga efter källa eller mål för en relation

Du kan använda relationsfrågestrukturen för att identifiera en digital tvilling som är källan eller målet för en relation.

Du kan till exempel börja med en källtvilling och följa dess relationer för att hitta måltvillingarna för relationerna. Här är ett exempel på en fråga som hittar måltvillingarna för feeds relationerna som kommer från tvillingens källtvilling.

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

Du kan också börja med målet för relationen och spåra relationen tillbaka för att hitta källtvillingen. Här är ett exempel på en fråga som hittar källtvillingen för en feeds relation till tvillingmåltvillingen.

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

Ställ frågor till en relations egenskaper

På liknande sätt som digitala tvillingar har egenskaper som beskrivs via DTDL så kan även relationer ha egenskaper. Du kan ställa frågor till tvillingar baserat på deras relationers egenskaper. Azure Digital Twins-frågespråket tillåter filtrering och projektion av relationer genom att tilldela ett alias till relationen i JOIN -satsen.

Tänk dig till exempel en servicedBy relation som har en reportedCondition egenskap. I frågan nedan får den här relationen ett alias R för för att referera till dess egenskap.

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

Observera i exemplet ovan hur reportedCondition är en egenskap för servicedBy själva relationen (INTE för någon digital tvilling som har en servicedBy relation).

Fråga med flera JOIN:er

Upp till fem JOINs stöds i en enda fråga, vilket gör att du kan korsa flera nivåer av relationer samtidigt.

Om du vill fråga efter flera nivåer av relationer använder du en enda FROM instruktion följt av N-instruktioner JOIN , där uttrycken JOIN uttrycker relationer på resultatet av en tidigare FROM instruktion eller JOIN -instruktion.

Här är ett exempel på en fråga med flera kopplingar, som hämtar alla glödlampor som finns i ljuspanelerna i rum 1 och 2.

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']

Räkna objekt

Du kan räkna antalet objekt i en resultatuppsättning med hjälp av Select COUNT -satsen:

SELECT COUNT()
FROM DIGITALTWINS

Lägg till en WHERE sats för att räkna antalet objekt som uppfyller ett visst villkor. Här är några exempel på att räkna med ett tillämpat filter baserat på typen av tvillingmodell (mer information om den här syntaxen finns i Fråga efter modell nedan):

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

Du kan också använda COUNT tillsammans med JOIN -satsen. Här är en fråga som räknar alla glödlampor som finns i ljuspanelerna i rum 1 och 2:

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']

Filterresultat: välj de översta objekten

Du kan välja flera "översta" objekt i en fråga med hjälp av Select TOP -satsen.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Filterresultat: ange returuppsättning med projektioner

Med hjälp av projektioner i -instruktionen SELECT kan du välja vilka kolumner en fråga ska returnera. Projektion stöds nu för både primitiva och komplexa egenskaper. Mer information om projektioner med Azure Digital Twins finns i referensdokumentationen för SELECT-satsen.

Här är ett exempel på en fråga som använder projektion för att returnera tvillingar och relationer. Följande fråga projicerar Konsument, Fabrik och Edge från ett scenario där en fabrik med ett ID ABC är relaterat till konsumenten via en relation till Factory.customeroch den relationen presenteras som Edge.

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

Du kan också använda projektion för att returnera en egenskap för en tvilling. Följande fråga projicerar Name egenskapen för de konsumenter som är relaterade till fabriken med ett ID ABC via en relation med Factory.customer.

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

Du kan också använda projektion för att returnera en egenskap för en relation. Precis som i föregående exempel projicerar Name följande fråga egenskapen För konsumenter som är relaterade till fabriken med ett ID ABC via en relation till Factory.customer, men nu returneras även två egenskaper för relationen, prop1 och prop2. Det gör den genom att namnge relationen Edge och samla in dess egenskaper.

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

Du kan också använda alias för att förenkla frågor med projektion.

Följande fråga utför samma åtgärder som i föregående exempel, men den aliaserar egenskapsnamnen till consumerName, first, secondoch 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'

Här är en liknande fråga som frågar samma uppsättning som ovan, men projekterar endast Consumer.name egenskapen som consumerNameoch projicerar hela Factory som en tvilling.

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

Skapa effektiva frågor med IN-operatorn

Du kan avsevärt minska antalet frågor som du behöver genom att skapa en matris med tvillingar och fråga med operatorn IN .

Tänk dig till exempel ett scenario där Byggnader innehåller Golv och Golv innehåller Rum. Om du vill söka efter rum i en byggnad som är varm är ett sätt att följa dessa steg.

1. Hitta golv i byggnaden baserat på contains relationen.

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

2. För att hitta rum, i stället för att överväga golven en i taget och köra en JOIN fråga för att hitta rummen för var och en, kan du fråga med en samling av våningarna i byggnaden (med namnet Floor i frågan nedan).

   I klientappen:

   var floors = "['floor1','floor2', ..'floorn']"; 
   

   I fråga:

   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')
   

Andra sammansatta frågeexempel

Du kan kombinera någon av ovanstående typer av frågor med hjälp av kombinationsoperatorer för att inkludera mer information i en enda fråga. Här är några andra exempel på sammansatta frågor som frågar efter mer än en typ av tvillingbeskrivning samtidigt.

• Av de enheter som rum 123 har returnerar du MxChip-enheterna som fungerar som operator

  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'
  

• Hämta tvillingar som har en relation med namnet Contains med en annan tvilling som har ett ID för id1

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

• Hämta alla rum i denna rumsmodell som finns på våning 11

  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')
  

Köra frågor med API:et

När du har bestämt dig för en frågesträng kör du den genom att anropa fråge-API:et.

Du kan anropa API:et direkt eller använda någon av de SDK:er som är tillgängliga för Azure Digital Twins.

Följande kodfragment illustrerar .NET-SDK-anropet (C#) från en klientapp:

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

Frågan som används i det här anropet returnerar en lista över digitala tvillingar, som exemplet ovan representerar med BasicDigitalTwin-objekt . Returtypen för dina data för varje fråga beror på vilka termer du anger med -instruktionen SELECT :

• Frågor som börjar med SELECT * FROM ... returnerar en lista över digitala tvillingar (som kan serialiseras som BasicDigitalTwin objekt eller andra anpassade typer av digitala tvillingar som du kan ha skapat).
• Frågor som börjar i formatet SELECT <A>, <B>, <C> FROM ... returnerar en ordlista med nycklarna <A>, <B>och <C>.
• Andra format för SELECT instruktioner kan skapas för att returnera anpassade data. Du kan överväga att skapa egna klasser för att hantera anpassade resultatuppsättningar.

Fråga med växling

Frågeanrop stöder växling. Här är ett komplett exempel som använder BasicDigitalTwin som frågeresultattyp med felhantering och växling:

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;
}

Nästa steg

Läs mer om Azure Digital Twins-API:er och SDK:er, inklusive fråge-API:et som används för att köra frågorna från den här artikeln.