Eseguire una query sul grafo di Gemelli digitali di Azure

Questo articolo offre esempi di query e istruzioni per l'uso del linguaggio di query di Gemelli digitali di Azure per eseguire query sul grafo del gemello per ottenere informazioni. Per un'introduzione al linguaggio di query, vedere Linguaggio di query.

L'articolo contiene query di esempio che illustrano la struttura del linguaggio di query e le operazioni di query comuni per gemelli digitali. Descrive anche come eseguire le query dopo averle scritte, usando l'API Query di Gemelli digitali di Azure o un SDK.

Nota

Se si eseguono le query di esempio seguenti con una chiamata API o SDK, è necessario condensare il testo della query in una singola riga.

Documentazione di riferimento

Le informazioni di riferimento sul linguaggio di query sono disponibili in Informazioni di riferimento nel sommario a sinistra per la documentazione di Gemelli digitali di Azure. È anche possibile passare direttamente alle sezioni di riferimento usando i link seguenti:

• Clausole
  • SELECT
  • FROM
  • MATCH
  • JOIN
  • WHERE
• Funzioni
• Operatori
• Parole chiave riservate

Visualizzare tutti i gemelli digitali

Ecco la query di base che restituirà un elenco di tutti i gemelli digitali nell'istanza:

SELECT * FROM DIGITALTWINS

Query in base a proprietà

Ottenere gemelli digitali in base alle proprietà (inclusi ID e metadati):

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

Come illustrato nella query precedente, viene eseguita una query sull'ID di un gemello digitale usando il campo dei metadati $dtId.

Suggerimento

Se si usa Cloud Shell per eseguire una query con campi di metadati che iniziano con $, è necessario eseguire l'escape $ con una barra rovesciata per informare Cloud Shell che non è una variabile e deve essere usata come valore letterale nel testo della query.

È anche possibile ottenere i gemelli in base alla definizione di una determinata proprietà. Ecco una query che ottiene i gemelli con una proprietà definita Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Questa query consente di ottenere gemelli in base alle relative tag proprietà, come descritto in Aggiungere tag ai gemelli digitali. Ecco una query che ottiene tutti i gemelli contrassegnati con red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

È anche possibile ottenere gemelli in base al tipo di una proprietà. Ecco una query che ottiene i gemelli la cui Temperature proprietà è un numero:

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

Proprietà della mappa delle query

Se una proprietà è di tipo Mapcomplesso , è possibile usare le chiavi e i valori della mappa direttamente nella query, come illustrato di seguito:

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

Se la chiave della mappa inizia con un carattere numerico, è necessario eseguire il wrapping della chiave tra parentesi quadre doppie ([[<mapKey>]]) per eseguirne l'escape nella query, analogamente alla strategia per l'esecuzione di query con parole chiave riservate.

Query in base al modello

L'operatore IS_OF_MODEL può essere usato per filtrare in base al modello del gemello.

Considera l'ereditarietà e il controllo delle versioni del modello e restituisce true per un determinato gemello se il gemello soddisfa una di queste condizioni:

• Il gemello implementa direttamente il modello fornito a IS_OF_MODEL()e il numero di versione del modello nel gemello è maggiore o uguale al numero di versione del modello fornito
• Il gemello implementa un modello che estende il modello fornito a IS_OF_MODEL()e il numero di versione estesa del modello del gemello è maggiore o uguale al numero di versione del modello fornito

Ad esempio, se si esegue una query per i gemelli del modello dtmi:example:widget;4, la query restituirà tutti i gemelli in base alla versione 4 o successiva del modello di widget e anche ai gemelli basati sulla versione 4 o successiva di tutti i modelli che ereditano dal widget.

IS_OF_MODEL può accettare diversi parametri e il resto di questa sezione è dedicato alle diverse opzioni di overload.

L'uso più semplice di IS_OF_MODEL accetta solo un twinTypeName parametro: IS_OF_MODEL(twinTypeName). Ecco un esempio di query che passa un valore in questo parametro:

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

Per specificare una raccolta di dispositivi gemelli in cui eseguire la ricerca quando sono presenti più di una raccolta ,ad esempio quando viene usato un JOIN oggetto , aggiungere il twinCollection parametro : IS_OF_MODEL(twinCollection, twinTypeName). Ecco un esempio di query che aggiunge un valore per questo parametro:

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

Per eseguire una corrispondenza esatta, aggiungere il exact parametro : IS_OF_MODEL(twinTypeName, exact). Ecco un esempio di query che aggiunge un valore per questo parametro:

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

È anche possibile passare insieme tutti e tre gli argomenti: IS_OF_MODEL(twinCollection, twinTypeName, exact). Ecco un esempio di query che specifica un valore per tutti e tre i parametri:

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

Query in base alla relazione

Quando si esegue una query in base alle relazioni dei gemelli digitali, il linguaggio di query di Gemelli digitali di Azure presenta una sintassi speciale.

Il pull delle relazioni viene eseguito nell'ambito della query nella clausola FROM. A differenza dei linguaggi di tipo SQL "classico", ogni espressione nella FROM clausola non è una tabella. La FROM clausola esprime invece un attraversamento di una relazione tra entità. Per attraversare le relazioni, Gemelli digitali di Azure usa una versione personalizzata di JOIN.

Tenere presente che con le funzionalità del modello di Gemelli digitali di Azure, le relazioni non esistono indipendentemente dai gemelli, ovvero le relazioni qui non possono essere sottoposte a query in modo indipendente e devono essere associate a un gemello. Per riflettere questo fatto, la parola chiave RELATED viene usata nella JOIN clausola per eseguire il pull nel set di un determinato tipo di relazione proveniente dalla raccolta di gemelli. La query deve quindi filtrare nella WHERE clausola per indicare quali gemelli specifici usare nella query di relazione (usando i valori dei $dtId gemelli).

Nelle sezioni seguenti vengono forniti esempi di questo aspetto.

Query di relazione di base

Ecco una query basata su relazioni di esempio. Questo frammento di codice seleziona tutti i gemelli digitali con una ID proprietà di ABCe tutti i gemelli digitali correlati a questi gemelli digitali tramite una contains relazione.

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

Il tipo della relazione (contains nell'esempio precedente) viene indicato usando il campo della name relazione dalla relativa definizione DTDL.

Nota

Lo sviluppatore non deve correlarlo JOIN con un valore di chiave nella WHERE clausola o specificare un valore chiave inline con la JOIN definizione. Questa correlazione viene calcolata automaticamente dal sistema, perché le proprietà della relazione identificano l'entità di destinazione.

Eseguire una query in base all'origine o alla destinazione di una relazione

È possibile usare la struttura di query di relazione per identificare un gemello digitale che è l'origine o la destinazione di una relazione.

Ad esempio, è possibile iniziare con un gemello di origine e seguire le relative relazioni per trovare i gemelli di destinazione delle relazioni. Di seguito è riportato un esempio di query che trova i gemelli di destinazione delle feeds relazioni provenienti dal gemello di origine gemello.

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

È anche possibile iniziare con la destinazione della relazione e tracciare di nuovo la relazione per trovare il gemello di origine. Ecco un esempio di query che trova il gemello di origine di una feeds relazione con il gemello.

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

Eseguire una query sulle proprietà di una relazione

Così come i gemelli digitali hanno proprietà descritte tramite DTDL, anche le relazioni possono avere proprietà. È possibile eseguire una query sui gemelli in base alle proprietà delle relazioni. Il linguaggio di query di Gemelli digitali di Azure consente di filtrare e proiettare le relazioni assegnando un alias alla relazione all'interno della JOIN clausola .

Si consideri ad esempio una servicedBy relazione con una reportedCondition proprietà . Nella query seguente, a questa relazione viene assegnato un alias di R per fare riferimento alla relativa proprietà.

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

Nell'esempio precedente si noti come reportedCondition è una proprietà della servicedBy relazione stessa (NOT di alcuni gemelli digitali con una servicedBy relazione).

Eseguire query con più JOIN

In una singola query sono supportati fino a cinque JOIN, che consente di attraversare più livelli di relazioni contemporaneamente.

Per eseguire query su più livelli di relazioni, usare una singola FROM istruzione seguita da istruzioni NJOIN, in cui le JOIN istruzioni esprimono relazioni sul risultato di un'istruzione o JOIN precedenteFROM.

Ecco un esempio di query multi join, che ottiene tutte le lampadine contenute nei pannelli luminosi nelle stanze 1 e 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']

Conteggio elementi

È possibile contare il numero di elementi in un set di risultati usando la Select COUNT clausola :

SELECT COUNT()
FROM DIGITALTWINS

Aggiungere una WHERE clausola per contare il numero di elementi che soddisfano un determinato criterio. Ecco alcuni esempi di conteggio con un filtro applicato in base al tipo di modello gemello (per altre informazioni su questa sintassi, vedere Eseguire query per modello di seguito):

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

È anche possibile usare COUNT insieme alla JOIN clausola . Ecco una query che conta tutte le lampadine contenute nei pannelli di luce delle stanze 1 e 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']

Risultati filtro: selezionare gli elementi principali

È possibile selezionare i diversi elementi "top" in una query usando la Select TOP clausola .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Risultati filtro: specificare il set restituito con le proiezioni

Usando le proiezioni nell'istruzione SELECT , è possibile scegliere le colonne restituite da una query. La proiezione è ora supportata per le proprietà primitive e complesse. Per altre informazioni sulle proiezioni con Gemelli digitali di Azure, vedere la documentazione di riferimento sulla clausola SELECT.

Ecco un esempio di query che usa la proiezione per restituire gemelli e relazioni. La query seguente proietta Consumer, Factory e Edge da uno scenario in cui una factory con ID ABC è correlata al consumer tramite una relazione di Factory.customere tale relazione viene presentata come Edge.

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

È anche possibile usare la proiezione per restituire una proprietà di un gemello. La query seguente proietta la Name proprietà dei consumer correlati alla factory con un ID di ABC tramite una relazione di Factory.customer.

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

È anche possibile usare la proiezione per restituire una proprietà di una relazione. Come nell'esempio precedente, la query seguente proietta la Name proprietà di Consumer correlati alla factory con un ID di ABC tramite una relazione di Factory.customer, ma ora restituisce anche due proprietà di tale relazione e prop1prop2. A tale scopo, denominare la relazione Edge e raccogliere le relative proprietà.

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

È anche possibile usare alias per semplificare le query con la proiezione.

La query seguente esegue le stesse operazioni dell'esempio precedente, ma aliasa i nomi delle proprietà in consumerName, firstsecond, e 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'

Ecco una query simile che esegue una query sullo stesso set di cui sopra, ma proietta solo la Consumer.name proprietà come consumerNamee proietta la factory completa come gemello.

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

Creare query efficienti con l'operatore IN

È possibile ridurre significativamente il numero di query necessarie creando una matrice di gemelli ed eseguendo query con l'operatore IN .

Si consideri, ad esempio, uno scenario in cui gli edifici contengono pavimenti e pavimenti contengono stanze. Per cercare stanze all'interno di un edificio caldo, un modo consiste nel seguire questi passaggi.

1. Trovare piani nell'edificio in base alla contains relazione.

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

2. Per trovare le stanze, invece di considerare i piani uno per uno ed eseguire una JOIN query per trovare le stanze per ognuna, è possibile eseguire una query con una raccolta di piani nell'edificio (denominata Floor nella query seguente).

   Nell'app client:

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

Altri esempi di query composte

È possibile combinare uno dei tipi di query precedenti usando operatori combinati per includere più dettagli in una singola query. Ecco alcuni altri esempi di query composte che eseguono query per più tipi di descrittore gemello contemporaneamente.

• Fuori dai dispositivi di cui dispone Room 123, restituire i dispositivi MxChip che fungono da operatore

  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'
  

• Ottenere i gemelli con una relazione denominata Contains con un altro gemello che ha un ID di id1

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

• Ottenere tutte le camere di questo modello di stanza che sono contenute da 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')
  

Eseguire query con l'API

Dopo aver stabilito una stringa di query, eseguirla eseguendo una chiamata all'API query.

È possibile chiamare direttamente l'API o usare uno degli SDK disponibili per Gemelli digitali di Azure.

Il frammento di codice seguente illustra la chiamata sdk .NET (C#) da un'app client:

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

La query usata in questa chiamata restituisce un elenco di gemelli digitali, che l'esempio precedente rappresenta con oggetti BasicDigitalTwin . Il tipo restituito dei dati per ogni query dipenderà dai termini specificati con l'istruzione SELECT :

• Le query che iniziano con SELECT * FROM ... restituiranno un elenco di gemelli digitali (che possono essere serializzati come BasicDigitalTwin oggetti o altri tipi di gemelli digitali personalizzati che potrebbero essere stati creati).
• Le query che iniziano nel formato SELECT <A>, <B>, <C> FROM ... restituiscono un dizionario con chiavi <A>, <B>e <C>.
• È possibile creare altri formati di SELECT istruzioni per restituire dati personalizzati. È possibile prendere in considerazione la creazione di classi personalizzate per gestire set di risultati personalizzati.

Query con paging

Le chiamate di query supportano il paging. Ecco un esempio completo che usa BasicDigitalTwin come tipo di risultato della query con gestione degli errori e 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;
}

Passaggi successivi

Altre informazioni sulle API e sugli SDK di Gemelli digitali di Azure, inclusa l'API query usata per eseguire le query di questo articolo.