Partager via

Informations de référence sur le langage de requête Azure Digital Twins : clause MATCH

  • Article

Ce document contient des informations de référence sur la clause MATCH du langage de requête Azure Digital Twins.

La clause MATCH est utilisée dans le langage de requête Azure Digital Twins dans le cadre de la clause FROM. MATCH vous permet de spécifier le modèle à suivre pour parcourir les relations dans le graphe Azure Digital Twins (également connu sous le nom de modèle de requête « saut de variable »).

Cette clause est facultative lors de l’interrogation.

Syntaxe principale : MATCH

MATCH prend en charge toutes les requêtes qui trouvent un chemin entre des jumeaux avec une plage de tronçons, en fonction de certaines conditions de relation.

La condition de relation peut inclure un ou plusieurs des détails suivants :

Une requête qui inclut une clause MATCH doit également utiliser la clause WHERE pour spécifier le $dtId d’au moins un des jumeaux auxquels elle fait référence.

Remarque

MATCH est un surensemble de toutes les requêtes JOIN qui peuvent être effectuées dans le magasin des requêtes.

Syntaxe

Voici la syntaxe MATCH de base.

Il contient les espaces réservés suivants :

--SELECT ... FROM ...  
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)
WHERE twin_or_twin_collection.$dtId = 'twin_ID' 
-- AND ...

Vous pouvez laisser une des collections de jumeaux vide afin de permettre à n’importe quel jumeau de travailler dans ce spot.

Vous pouvez également modifier le nombre de conditions de relation pour avoir plusieurs conditions de relation chaînées ou aucune condition de relation :

--Chained relationship conditions
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)-[relationship_condition]-(twin_or_twin_collection_3)...
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

-- No relationship condition
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

Pour plus d’informations sur chaque type de condition de relation et sur la manière de les combiner, consultez les autres sections de ce document.

Exemple

Voici un exemple de requête qui utilise MATCH.

La requête spécifie une direction de relation, puis recherche des jumeaux Building et Sensor où :

  • Sensor est ciblé par toute relation à partir d’un jumeau Building dont la valeur $dtId est Building21, et
  • Sensor indique une température supérieure à 50. Building et Sensor sont tous les deux inclus dans le résultat de la requête.
SELECT Building, Sensor FROM DIGITALTWINS 
MATCH (Building)-[]->(Sensor) 
WHERE Building.$dtId = 'Building21' AND Sensor.temperature > 50

Spécifier la direction de la relation

Utilisez la condition de relation dans la clause MATCH pour spécifier une direction de relation entre les jumeaux. Les directions possibles sont les suivants : de gauche à droite, de droite à gauche ou non directionnelle. Les relations cycliques sont automatiquement détectées, afin qu’une relation ne soit traversée qu’une seule fois.

Remarque

Il est possible de représenter des relations bidirectionnelles en utilisant un chaînage.

Syntaxe

Remarque

Les exemples de cette section se concentrent sur la direction de la relation. Ils ne spécifient pas de noms de relation, leur valeur par défaut correspond à un saut unique et ils n’affectent pas de variables de requête aux relations. Pour obtenir des instructions sur l’utilisation de ces autres conditions, consultez Spécifier le nom de la relation, Spécifier le nombre de sauts et Affecter une variable de requête à une relation. Pour plus d’informations sur l’utilisation simultanée de plusieurs de ces conditions dans la même requête, consultez Combiner des opérations MATCH.

Les descriptions de relations directionnelles utilisent une représentation visuelle d’une flèche pour indiquer la direction de la relation. La flèche inclut un espace réservé par des crochets ([]) à un éventuel nom de relation.

Cette section présente la syntaxe de différentes directions de relation. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont source_twin_or_twin_collection et target_twin_or_twin_collection.

Pour une relation de gauche à droite, utilisez la syntaxe suivante.

-- SELECT ... FROM ...
MATCH (source_twin_or_twin_collection)-[]->(target_twin_or_twin_collection)
-- WHERE ...

Pour une relation de droite à gauche, utilisez la syntaxe suivante.

-- SELECT ... FROM ...
MATCH (target_twin_or_twin_collection)<-[]-(source_twin_or_twin_collection)
-- WHERE ...

Pour une relation non directionnelle, utilisez la syntaxe suivante. Celle-ci ne spécifie pas de direction pour la relation, si bien que des relations de toute direction sont incluses dans le résultat.

-- SELECT ... FROM ...
MATCH (source_twin_or_twin_collection)-[]-(target_twin_or_twin_collection)
-- WHERE ...

Conseil

Les requêtes non directionnelles nécessitent un traitement supplémentaire, susceptible d’entraîner une latence et un coût accrus.

Exemples

Le premier exemple montre une traversée directionnelle de gauche à droite. Cette requête recherche des jumeaux Room et Factory où :

  • Room cible Factory (quel que soit le nom de la relation).
  • Room présente une valeur de température supérieure à 50.
  • Factory a la valeur $dtId définie sur « ABC ».
SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)-[]->(Factory) 
WHERE Room.temperature > 50 AND Factory.$dtId = 'ABC'

Remarque

Les requêtes MATCH qui contiennent des filtres $dtId sur tout jumeau autre que le jumeau de départ de la traversée MATCH peuvent afficher des résultats vides. Cela s’applique à factory.$dtId dans l’exemple ci-dessus. Pour plus d’informations, consultez Limitations.

L’exemple suivant montre une traversée directionnelle de gauche à droite. Cette requête ressemble à celle ci-dessus, mais la direction de la relation entre Room et Factory est inversée. Cette requête recherche des jumeaux Room et Factory où :

  • Factory cible Room (quel que soit le nom de la relation).
  • Factory a la valeur $dtId définie sur « ABC ».
  • Room présente une valeur de température supérieure à 50.
SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)<-[]-(Factory) 
WHERE Factory.$dtId = 'ABC' AND Room.temperature > 50

L’exemple suivant montre une traversée non directionnelle. Cette requête recherche des jumeaux Room et Factory où :

  • Room et Factory partagent n’importe quel nom de relation, dans l’une ou l’autre direction.
  • Factory a la valeur $dtId définie sur « ABC ».
  • Room présente une valeur de taux d’humidité supérieure à 70.
SELECT Factory, Room FROM DIGITALTWINS MATCH (Factory)-[]-(Room) 
WHERE Factory.$dtId ='ABC'  AND Room.humidity > 70

Spécifier le nom de la relation

Éventuellement, vous pouvez utiliser la condition de relation dans la clause MATCH pour spécifier les noms des relations entre les jumeaux. Vous pouvez spécifier un nom unique ou une liste de noms possibles. Le nom de relation facultatif est inclus dans le cadre de la syntaxe de flèche pour spécifier la direction de la relation.

Si vous ne fournissez pas de nom de relation, la requête inclut tous les noms de relation par défaut.

Conseil

La spécification de noms de relation dans la requête peut améliorer les performances et rendre les résultats plus prédictibles.

Syntaxe

Remarque

Les exemples de cette section se concentrent sur le nom de la relation. Ils présentent tous des relations non directionnelles, leur valeur par défaut correspond à un saut unique et ils n’affectent pas de variables de requête aux relations. Pour obtenir des instructions sur l’utilisation de ces autres conditions, consultez Spécifier la direction de la relation, Spécifier le nombre de sauts et Affecter une variable de requête à une relation. Pour plus d’informations sur l’utilisation simultanée de plusieurs de ces conditions dans la même requête, consultez Combiner des opérations MATCH.

Spécifiez le nom d’une relation à traverser dans la clause MATCH entre crochets ([]), après un signe deux-points (:). Cette section décrit la syntaxe de la spécification de relations nommées.

Pour un nom unique, utilisez la syntaxe suivante. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1, relationship_name et twin_or_twin_collection_2.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[:relationship_name]-(twin_or_twin_collection_2)
-- WHERE ...

Pour plusieurs noms possibles, utilisez la syntaxe suivante. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1, relationship_name_option_1, relationship_name_option_2, twin_or_twin_collection_2 et la remarque indiquant de continuer le modèle selon les besoins en termes de nombre de noms de relation à entrer.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[:relationship_name_option_1|relationship_name_option_2|continue pattern as needed...]-(twin_or_twin_collection_2)
-- WHERE ...

Important

Le signe deux-points (:) entre crochets est une partie requise de la syntaxe pour spécifier un nom de relation dans une requête MATCH. Si vous n’incluez pas le signe deux-points, votre requête ne spécifie pas de nom de relation. Au lieu de cela, vous disposez d’une requête qui attribue une variable de requête à la relation.

(Par défaut) Pour ne pas spécifier de nom, laissez les crochets vides, comme ceci :

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[]-(twin_or_twin_collection_2)
-- WHERE ...

Exemples

L’exemple suivant montre un nom de relation unique. Cette requête recherche des jumeaux Building et Sensor où :

  • Building a une relation « contains » avec Sensor (dans l’une ou l’autre direction).
  • Building a la valeur $dtId définie sur « Seattle21 ».
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

L’exemple suivant montre plusieurs noms de relation possibles. Cette requête ressemble à celle ci-dessus, mais plusieurs noms de relation possibles sont inclus dans le résultat. Cette requête recherche des jumeaux Building et Sensor où :

  • Building a une relation « contains » ou « isAssociatedWith » avec Sensor (dans l’une ou l’autre direction).
  • Building a la valeur $dtId définie sur « Seattle21 ».
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains|isAssociatedWith]-(Sensor)  
WHERE building.$dtId = 'Seattle21'

L’exemple suivant n’a aucun nom de relation spécifié. Ainsi, les relations sont incluses dans le résultat de la requête, quel que soit leur nom. Cette requête recherche des jumeaux Building et Sensor où :

  • Building a une relation avec Sensor d’un nom quelconque (dans l’une ou l’autre direction).
  • Building a la valeur $dtId définie sur « Seattle21 ».
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building-[]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

Spécifier le nombre de sauts

Éventuellement, vous pouvez utiliser la condition de relation dans la clause MATCH pour spécifier le nombre de sauts pour les relations entre les jumeaux. Vous pouvez spécifier un nombre exact ou une plage. La valeur facultative est incluse dans le cadre de la syntaxe de flèche pour spécifier la direction de la relation.

Si vous n’indiquez pas le nombre de sauts, ce dernier est égal à un par défaut dans la requête.

Important

Si vous spécifiez un nombre de sauts supérieur à un, vous ne pouvez pas affecter une variable de requête à la relation. Une seule de ces conditions peut être utilisée au sein de la même requête.

Syntaxe

Remarque

Les exemples de cette section se concentrent sur le nombre de sauts. Ils présentent tous des relations non directionnelles sans spécifier de noms. Pour obtenir des instructions sur l’utilisation de ces autres conditions, consultez Spécifier la direction de la relation et Spécifier le nom de la relation. Pour plus d’informations sur l’utilisation simultanée de plusieurs de ces conditions dans la même requête, consultez Combiner des opérations MATCH.

Spécifiez le nombre de sauts à traverser dans la clause MATCH entre crochets ([]).

Pour spécifier un nombre exact de sauts, utilisez la syntaxe suivante. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1, number_of_hops et twin_or_twin_collection_2.

-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[*number_of_hops]-(twin_or_twin_collection_2)
-- WHERE ...

Pour spécifier une plage de sauts, utilisez la syntaxe suivante. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1, starting_limit, ending_limit et twin_or_twin_collection_2. La limite de début n’est pas incluse dans la plage, alors que la limite de fin est incluse.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[*starting_limit..ending_limit]-(twin_or_twin_collection_2)
-- WHERE ...

Vous pouvez aussi omettre la limite de début pour indiquer « toute valeur allant jusqu’à » la limite de fin (incluse). Une limite de fin doit toujours être fournie.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[*..ending_limit]-(twin_or_twin_collection_2)
-- WHERE ...

(Par défaut) Pour spécifier un seul saut par défaut, laissez les crochets vides, comme ceci :

-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[]-(twin_or_twin_collection_2)
-- WHERE ...

Exemples

L’exemple suivant spécifie un nombre exact de sauts. La requête va uniquement retourner les relations entre les jumeaux Floor et Room dont le nombre de sauts est strictement égal à 3.

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*3]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

L’exemple suivant spécifie une plage de sauts. La requête va retourner les relations entre les jumeaux Floor et Room comprises entre 1 et 3 sauts (ce qui signifie que le nombre de sauts est égal à 2 ou 3).

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*1..3]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

Vous pouvez aussi présenter une plage en ne fournissant qu’une seule limite. Dans l’exemple suivant, la requête va retourner les relations entre les jumeaux Floor et Room comprenant au maximum 2 sauts (ce qui signifie que le nombre de sauts est égal à 1 ou 2).

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*..2]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

L’exemple suivant n’a aucun nombre spécifié de sauts. Donc, par défaut, un seul saut entre les jumeaux Floor et Room est défini.

SELECT Floor, Room FROM DIGITALTWINS  
MATCH (Floor)-[]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

Affecter une variable de requête à une relation (et spécifier des propriétés de relation)

Vous pouvez éventuellement affecter une variable de requête à la relation référencée dans la clause MATCH, pour pouvoir y faire référence par son nom dans le texte de la requête.

Ainsi, vous avez alors la possibilité de filtrer les propriétés de relation dans votre clause WHERE.

Important

L’affectation d’une variable de requête à la relation est prise en charge uniquement quand la requête spécifie un seul saut. Au sein d’une requête, vous devez choisir entre la spécification d’une variable de relation et la spécification d’un nombre supérieur de sauts.

Syntaxe

Remarque

Les exemples de cette section se concentrent sur une variable de requête pour la relation. Ils présentent tous des relations non directionnelles sans spécifier de noms. Pour obtenir des instructions sur l’utilisation de ces autres conditions, consultez Spécifier la direction de la relation et Spécifier le nom de la relation. Pour plus d’informations sur l’utilisation simultanée de plusieurs de ces conditions dans la même requête, consultez Combiner des opérations MATCH.

Pour affecter une variable de requête à la relation, placez le nom de la variable entre crochets ([]). Les valeurs d’espace réservé indiquées ci-dessous que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1, relationship_variable et twin_or_twin_collection_2.

-- SELECT ... FROM ...   
MATCH (twin_or_twin_collection_1)-[relationship_variable]-(twin_or_twin_collection_2>) 
-- WHERE ...

Exemples

L’exemple suivant attribue une variable de requête 'Rel' à la relation. Plus loin, dans la clause WHERE, l’exemple utilise la variable pour spécifier que la relation Rel doit avoir une propriété de nom dont la valeur est « child ».

SELECT Floor,Cafe, Rel DIGITALTWINS   
MATCH (Floor)-[Rel]-(Cafe)  
WHERE Floor.$dtId = 'thermostat-15' AND Rel.name = 'child'

Combiner des opérations MATCH

Vous pouvez combiner plusieurs conditions de relation dans la même requête. Vous pouvez aussi chaîner plusieurs conditions de relation pour exprimer des relations bidirectionnelles ou d’autres combinaisons plus larges.

Syntaxe

Dans une requête unique, vous pouvez combiner la direction de la relation, le nom de la relation et soit le nombre de tronçons, soit une affectation de variable de requête.

Les exemples de syntaxe suivants montrent comment ces attributs peuvent se combiner. Vous pouvez aussi exclure les informations facultatives présentées dans les espaces réservés pour omettre cette partie de la condition.

Pour spécifier la direction de la relation, le nom de la relation et le nombre de sauts au sein d’une seule requête, utilisez la syntaxe suivante dans la condition de relation. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1 et twin_or_twin_collection_2, optional_left_angle_bracket et optional_right_angle_bracket, relationship_name(s), puis number_of_hops.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)optional_left_angle_bracket-[:relationship_name(s)*number_of_hops]-optional_right_angle_bracket(twin_or_twin_collection_2)
-- WHERE

Pour spécifier la direction de la relation, le nom de la relation et une variable de requête pour la relation au sein d’une seule requête, utilisez la syntaxe suivante dans la condition de relation. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1 et twin_or_twin_collection_2, optional_left_angle_bracket et optional_right_angle_bracket, relationship_variable, puis relationship_name(s).

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)optional_left_angle_bracket-[relationship_variable:relationship_name(s)]-optional_right_angle_bracket(twin_or_twin_collection_2)
-- WHERE

Remarque

Conformément aux options de spécification de la direction de la relation, vous devez choisir entre un chevron gauche pour une relation de gauche à droite et un chevron droit pour une relation de droite à gauche. Vous ne pouvez pas inclure les deux dans la même flèche, mais vous pouvez représenter des relations bidirectionnelles par un chaînage.

Vous pouvez chaîner plusieurs conditions de relation ensemble, comme dans cet exemple. Les valeurs d’espace réservé que vous devez remplacer par vos valeurs sont twin_or_twin_collection_1, toutes les instances de relationship_condition et twin_or_twin_collection_2.

--Chained relationship conditions
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)-[relationship_condition]-(twin_or_twin_collection_3)...
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

Exemples

Voici un exemple qui combine la direction de la relation, le nom de la relation et le nombre de sauts. La requête suivante trouve les jumeaux Floor et Room pour lesquels la relation entre Floor et Room remplit ces conditions :

  • La relation est de gauche à droite, avec Floor comme source et Room comme cible.
  • Le nom de la relation comporte 'contains' ou 'isAssociatedWith'.
  • La relation comporte 4 ou 5 sauts.

La requête spécifie aussi que le jumeau Floor a la valeur $dtId définie sur « thermostat-15 ».

SELECT Floor, Room FROM DIGITALTWINS    
MATCH (Floor)-[:contains|isAssociatedWith*3..5]->(Room) 
WHERE Floor.$dtId = 'thermostat-15'

Voici un exemple qui combine la direction de la relation, le nom de la relation et une variable de requête nommée pour la relation. La requête suivante trouve les jumeaux Floor et Room, pour lesquels la relation entre Floor et Room est affectée à une variable de requête r et remplit ces conditions :

  • La relation est de gauche à droite, avec Floor comme source et Room comme cible.
  • Le nom de la relation comporte 'contains' ou 'isAssociatedWith'.
  • La relation, qui reçoit une variable de requête r, a une propriété de longueur égale à 10

La requête spécifie aussi que le jumeau Floor a la valeur $dtId définie sur « thermostat-15 ».

SELECT Floor, Room FROM DIGITALTWINS    
MATCH (Floor)-[r:contains|isAssociatedWith]->(Room) 
WHERE Floor.$dtId = 'thermostat-15' AND r.length = 10

L’exemple suivant illustre des conditions de relation chaînées. La requête trouve les jumeaux Floor, Cafe et Room, où :

  • La relation entre Floor et Room remplit ces conditions :
    • La relation est de gauche à droite, avec Floor comme source et Cafe comme cible.
    • Le nom de la relation comporte 'contains' ou 'isAssociatedWith'.
    • La relation, qui reçoit la variable de requête r, a une propriété de longueur égale à 10
  • La relation entre Cafe et Room remplit ces conditions :
    • La relation est de droite à gauche, avec Room comme source et Cafe comme cible.
    • Le nom de la relation comporte soit 'has', soit 'includes'.
    • La relation compte jusqu’à 3 (à savoir 1, 2 ou 3) sauts.

La requête spécifie aussi que le jumeau Floor a une valeur $dtId définie sur « thermostat-15 », et que le jumeau Cafe a une température égale à 55.

SELECT Floor,Room, Cafe FROM DIGITALTWINS    
MATCH (Floor)-[r:contains|isAssociatedWith]->(Cafe)<-[has|includes*..3]-(Room)  
WHERE Floor.$dtId = 'thermostat-15'  AND r.length = 10 AND Cafe.temperature = 55

Vous pouvez aussi utiliser des conditions de relation chaînées pour exprimer des relations bidirectionnelles. La requête suivante recherche les jumeaux Floor, Room et Building, où :

  • La relation entre Building et Floor remplit ces conditions :
    • La relation est de gauche à droite, avec Building comme source et Floor comme cible.
    • Le nom de la relation comporte 'isAssociatedWith'.
    • La relation reçoit une variable de requête r1
  • La relation entre Floor et Room remplit ces conditions :
    • La relation est de droite à gauche, avec Room comme source et Floor comme cible.
    • Le nom de la relation comporte 'isAssociatedWith'.
    • La relation reçoit une variable de requête r2

La requête spécifie aussi que le jumeau Building a une valeur $dtId définie sur « building-3 », et que Room présente une température supérieure à 50.

SELECT Floor, Room, Building FROM DIGITALTWINS    
MATCH (Building)-[r1:isAssociatedWith]->(Floor)<-[r2:isAssociatedWith]-(Room)
WHERE Building.$dtId = 'building-3'  AND Room.temperature > 50

Limites

Les limites suivantes s’appliquent aux requêtes qui utilisent MATCH :

  • Une seule expression MATCH est prise en charge par instruction de requête.

  • $dtId est nécessaire dans la clause WHERE.

  • L’affectation d’une variable de requête à la relation est prise en charge uniquement quand la requête spécifie un seul saut.

  • Le nombre maximal de tronçons pris en charge dans une requête s’élève à 10.

  • Les requêtes MATCH qui contiennent des filtres $dtId sur tout jumeau autre que le jumeau de départ de la traversée MATCH peuvent afficher des résultats vides. Par exemple, la requête suivante est soumise à cette limitation :

    SELECT A, B, C FROM DIGITALTWINS 
MATCH A-[contains]->B-[is_part_of]->C 
WHERE B.$dtId = 'Device01'

    Si votre scénario nécessite que vous utilisiez $dtId sur d’autres jumeaux, envisagez d’utiliser la clause JOIN à la place.

  • Les requêtes MATCH qui traversent le même jumeau plusieurs fois peuvent supprimer ce jumeau des résultats de manière inattendue.