Interroger un graphe de connaissances

Vous pouvez interroger un graphe de connaissances pour rechercher un sous-ensemble des entités et des relations qu’il contient et voir comment différentes entités sont connectées. Les enregistrements de provenance peuvent être utilisés et éventuellement inclus dans les résultats de la requête. Consultez les exemples ci-dessous :

• À partir d’un graphe de connaissances représentant la propagation d’une maladie infectieuse, examinez les personnes et les animaux associés via une relation avec une ressource donnée.
• À partir d’un graphe de connaissances représentant une chaîne d’approvisionnement de fabrication, examinez le contenu associé à un composant spécifique, y compris les fournisseurs, les moyens de livraison, les entrepôts, etc.
• À partir d’un graphe de connaissances représentant une organisation, examinez les appareils d’un type donné et répertoriez-en les propriétés, y compris le nom de l’employé responsable.
• À partir d’un graphe de connaissances représentant les tortues et leurs habitats, identifiez les habitats où le niveau de risque a été établi à l’aide des informations d’une évaluation spécifique de l’impact environnemental.

Vous pouvez identifier le sous-ensemble d’entités et de relations, ou leurs propriétés, en interrogeant le graphe de connaissances. Utilisez le langage de requête openCypher pour écrire des requêtes openCypher afin de découvrir les entités associées et leurs propriétés et utilisez cet ensemble restreint d’informations dans le graphe de connaissances, une carte ou un diagramme de liens.

Écrire une requête openCypher

Les requêtes openCypher sont aux bases de données orientées graphe ce que les requêtes SQL sont aux bases de données relationnelles. La structure de base de la requête consiste à rechercher, ou faire correspondre, les entités et de renvoyer ces entités, lorsque les entités que vous recherchez sont identifiées entre parenthèses. Par exemple, la requête MATCH (e) RETURN e renvoie des entités de n’importe quel type. Le nombre d’entités renvoyées est limité uniquement par la configuration du graphe de connaissances. Pour restreindre le nombre d’éléments de graphe renvoyés, utilisez une expression LIMIT. Par exemple, la requête MATCH (e) RETURN e LIMIT 5 renvoie cinq entités de n’importe quel type.

La requête peut identifier les entités qui sont liées à l’aide de symboles qui créent une flèche. Par exemple, la requête MATCH (e1)-->(e2) RETURN e1,e2 renvoie des paires d’entités, e1 et e2, dans lesquelles n’importe quel type de relation existe entre les deux entités et n’importe quel chemin de l’entité e1 à l’entité e2 les connecte. Si la requête a été écrite avec la flèche pointant dans l’autre direction, les chemins doivent être considérés comme démarrant de l’entité d’origine e2 vers l’entité de destination e1 : MATCH (e1)<--(e2) RETURN e1,e2. La relation entre les entités est appelée un modèle.

La requête peut identifier des relations spécifiques qui doivent être placées entre crochets. Par exemple, la requête MATCH (e1)-[]->(e2) RETURN e1,e2 renvoie des paires d’entités, e1 et e2, dans lesquelles une seule relation de n’importe quel type connecte les deux entités. Cette requête présente une autre manière de représenter les mêmes requêtes que celles illustrées ci-dessus, et illustre la syntaxe de requête préférée. La requête peut être modifiée pour renvoyer l’intégralité du tuple qui décrit la relation en renvoyant l’entité d’origine, e1, la relation, r, et l’entité de destination, e2, comme suit : MATCH (e1)-[r]->(e2) RETURN e1,r,e2. Des requêtes similaires, MATCH (e1)-[ ]->( )-[ ]->(e2) RETURN e1,e2 ou MATCH (e1)-[*2]->(e2) RETURN e1,e2, renvoie des paires d’entités connectées par deux relations dans la même direction. Les requêtes peuvent également identifier des modèles dans lesquels les relations présentent des directions différentes, comme MATCH (e1)-[ ]->(e2)<-[ ]-(e3) RETURN e1,e2,e3.

Les exemples de requêtes ci-dessus peuvent être utilisés avec n’importe quel graphe de connaissances.

Personnalisez une requête pour un graphe de connaissances spécifique en référençant les types d’entité, les types de relation et les propriétés définies dans son modèle de données. Incluez le nom d’un type d’entité spécifique dans votre requête pour contraindre les éléments de graphe pris en compte. Par exemple, la requête MATCH (e1:Person)-[r]->(e2) RETURN e1,r,e2 renvoie toutes les entités Person (Personne), e1, dans lesquelles une relation, r, connecte l’entité Person (Personne) à une autre entité, e2, qui peut être une entité de n’importe quel type. Contrairement à l’exemple précédent, les relations dans lesquelles une entité d’animal, de véhicule ou de document est utilisée comme origine d’une relation ne sont pas incluses dans les résultats.

Vous pouvez contraindre la requête afin de prendre en compte certains types de relation et certaines entités liées en ajoutant les types de relation et d’entité aux autres facettes de la requête. Par exemple, MATCH (p:Person)-[v:HasVehicle]->(e) RETURN p,v,e renvoie toutes les entités Person (Personne), p, dans lesquelles une relation HasVehicle (Possède un véhicule), v, connecte l’entité Person (Personne) à une entité de n’importe quel type, e. Les variables p et v sont attribuées respectivement aux entités Person (Personne) et aux relations HasVehicle (Possède un véhicule). Les informations les concernant peuvent donc être retournées par la requête. Contrairement à l’exemple précédent, les relations dans lesquelles une entité d’animal ou de document est utilisée comme destination d’une relation ne sont pas incluses dans les résultats. En fonction du modèle de données du graphe de connaissances, l’entité de destination, e, peut être une entité de véhicule générique, ou une entité d’un type spécifique, comme une entité de voiture, de moto, de bateau, d’avion, d’utilitaire, etc.

Les propriétés spécifiques des entités et des relations peuvent être incluses dans les résultats de requête. Par exemple, MATCH (p:Person)-[:HasVehicle]->(e) RETURN p,e.make,e.model,e.year exécute la même requête que celle définie précédemment. Toutefois, au lieu de montrer l’entité de destination, les résultats montrent les valeurs stockées dans plusieurs de ses propriétés : la marque, le modèle et l’année du véhicule, respectivement. Dans cet exemple, aucune variable n’a été affectée à la relation prise en compte par la requête, car les données de la relation ne sont pas incluses dans les résultats de requête ni évaluées ailleurs dans la requête.

De même, vous pouvez contraindre les entités et les relations qui sont évaluées en spécifiant des propriétés qui définissent les entités et les relations d’intérêt. Les propriétés à prendre en compte sont définies par l’ajout d’une clause WHERE à la requête. Comme dans les exemples ci-dessus, les variables doivent être affectées pour faire référence à des informations spécifiques à propos des entités et des relations dans la clause WHERE. Par exemple, dans la requête suivante, seules les entités Person (Personne) avec une valeur spécifique pour la propriété lastName (nom) sont évaluées ; les relations HasVehicle (Possède un véhicule) sont prises en compte uniquement si la valeur de leur propriété endDate (date de fin) est nulle ; et les entités Vehicle (Véhicule) liées sont uniquement prises en compte si la valeur de la propriété year (année) est inférieure à 1980 : MATCH (p:Person)-[hv:HasVehicle]->(v:Vehicle) WHERE p.lastName = 'Doe' and hv.endDate IS NULL and v.year < 1980 RETURN p,p.firstName,v,v.make,v.year.

Au lieu de renvoyer une série d’entités et de relations individuelles, votre requête peut retourner le chemin complet que représente un modèle. Pour ce faire, affectez le modèle défini dans l’instruction MATCH à une variable et renvoyez cette variable. Par exemple, la requête MATCH path = (:Person)-[:HasVehicle]->(:Vehicle) RETURN path renvoie une liste de chemins pour toutes les associations d’entités et de relations qui correspondent au modèle spécifié. Chaque chemin contient des parties du modèle correspondant : l’entité Person (Personne), la relation HasVehicle (Possède un véhicule) et l’entité Vehicle (Véhicule). Il n’est pas nécessaire d’affecter des variables à des parties individuelles de ce modèle, car elles ne sont pas renvoyées par la requête.

Utiliser des valeurs date-heure dans une requête

Pour créer un graphe de connaissances à l’aide d’un graph store hébergé ou d’un data store NoSQL avec des données gérées par ArcGIS, les valeurs date-heure doivent toujours être exprimées en temps universel coordonné (UTC). De même, les valeurs date-heure renvoyées par une requête se présentent toujours au format UTC. Autrement dit, les valeurs date-heure stockées dans une propriété d’une entité ou d’une relation ne peuvent pas être associées à un fuseau horaire spécifique. Les valeurs date-time définies sont stockées en l’état. Cela signifie que le graphe de connaissances ne convertit pas automatiquement une valeur définie dans l’heure locale en heure UTC. Vous devez faire la conversion vous-même et stocker la valeur correcte pour éviter que des problèmes ne surviennent lors d’une future interrogation du graphe de connaissances.

Par exemple, dans le cas de la collecte de données portant sur un événement particulier, tous les utilisateurs chargés de mettre à jour le graphe de connaissances doivent définir les valeurs date-heure relatives à cet événement au format UTC approprié. Les éditeurs situés dans des fuseaux horaires différents ne doivent pas indiquer la valeur date-heure associée à leur fuseau horaire local. De même, pour interroger le graphe de connaissances, les requêtes doivent référencer l’heure UTC appropriée associée à l’événement, et non l’heure locale de votre fuseau horaire. Ainsi, tous les utilisateurs stockeront des valeurs correctes et pourront interroger les valeurs correctes quelles que soient leur position physique et leur heure locale.

Pour interroger un graphe de connaissances sur la base de valeurs stockées dans des propriétés de date, vous devez utiliser l’utilitaire datetime() qui interprète la valeur définie comme une date. Utilisez le format date-heure YYYY-MM-DDThh:mm:ss.sssZ pour exprimer la date et l’heure définies en heure UTC. Utilisez le format date-heure YYYY-MM-DDThh:mm:ss.sss+00:00 pour exprimer la date définie en heure locale avec mention du décalage de fuseau horaire. Une valeur date-heure complète doit être définie au format ISO avec mention d’un fuseau horaire. S’il manque le fuseau horaire ou certaines partie de la valeur date-heure, la requête renvoie une erreur.

Par exemple, pour rechercher tous les véhicules achetés après une date et une heure spécifiques, utilisez une requête du type MATCH path=(:Person)-[hv:HasVehicle]->(:Vehicle) WHERE hv.acquisitionDate > datetime('2014-10-18T12:36-08:00') RETURN path. Tous les chemins renvoyés coïncident avec une relation HasVehicle dont la propriété acquisitionDate a une valeur postérieure à 12 h 36 heure normale du Pacifique le 18 octobre 2014 ; l’heure UTC a huit heures d’avance sur l’heure normale du Pacifique

Pour rechercher tous les véhicules achetés en 1998, utilisez une requête du type MATCH path=(:Person)-[hv:HasVehicle]->(:Vehicle) WHERE hv.acquisitionDate > datetime('1998-01-01T00:00Z') and hv.acquisitionDate < datetime('1998-12-31T23:59Z') RETURN path. Tous les chemins renvoyés coïncident avec une relation HasVehicle dont la propriété acquisitionDate est comprise entre le 1er janvier 1998 et le 31 décembre 1998 à minuit en heure UTC.

Actuellement, ArcGIS Knowledge ne prend pas en charge l’interrogation d’un graphe de connaissances sur un intervalle temporel ou une période.

Utiliser des enregistrements de provenance dans une requête

Lorsque vous créez un graphe de connaissances à l’aide d’un graph store hébergé ou d’un data store NoSQL avec des données gérées par ArcGIS, vous pouvez activer la provenance. Les enregistrements de provenance vous permettent de spécifier l’origine du contenu du graphe de connaissances. Vous pouvez indiquer que la valeur stockée dans une propriété d’une entité ou d’une relation a été dérivée d’un document ou d’un site Web spécifique. Ces informations peuvent être utilisées ultérieurement lorsque vous interrogez le graphe de connaissances. Vous pouvez rechercher des entités et des relations dont les valeurs de propriété proviennent d’une source d’information particulière.

Par défaut, les enregistrements de provenance sont exclus de toutes les requêtes. Dans ArcGIS Pro, vous devez cocher l’option Include Provenance (Inclure la provenance) pour pouvoir exploiter les informations stockées dans les enregistrements de provenance dans une requête et inclure les enregistrements de provenance dans les résultats de la requête. Si vous créez une application personnalisée qui communique avec un site ArcGIS Knowledge Server à l’aide d’une des API de développement disponibles, l’application cliente doit indiquer que les résultats de la requête devraient inclure les enregistrements de provenance.

La requête doit identifier les entités et les relations dont les propriétés sont associées à des enregistrements de provenance en comparant les identifiants d’instance des éléments de graphe aux identifiants d’instance stockés dans les enregistrements de provenance. La requête peut également évaluer les propriétés des éléments de graphe et les enregistrements de provenance pour obtenir des résultats. Les enregistrements de provenance eux-mêmes ou leurs propriétés peuvent également être inclus dans les résultats de la requête.

Par exemple, pour rechercher les propriétaires de tous les véhicules pour lesquels la source d’information California Department of Motor Vehicles est stockée dans les propriétés de la relation HasVehicle, vous pouvez utiliser la requête MATCH (p:Person)-[hv:HasVehicle]->(v:Vehicle), (pr:Provenance) WHERE ID(hv)=pr.instanceID and pr.sourceName ="California Department of Motor Vehicles" RETURN p,hv,v,pr. La requête identifie les relations HasVehicle dotées d’enregistrements de provenance en comparant les identifiants d’instance des relations à la propriété instanceID des enregistrements de provenance. Les enregistrements de provenance évalués sont uniquement ceux dont la propriété sourceName de l’enregistrement possède la valeur appropriée. Les entités Person et Vehicle associées aux relations HasVehicle trouvées, ainsi que les enregistrements de provenance eux-mêmes sont également inclus dans les résultats de la requête.

Utiliser des opérateurs spatiaux dans une requête

ArcGIS Knowledge prend en charge l’utilisation des opérateurs spatiaux dans les requêtes openCypher avec des géométries de type point, multi-point, ligne et polygone. Ce sont les types de géométrie pris en charge pour les types d’entité créés dans graphe de connaissances à l’aide d’un graph store hébergé ou d’un data store NoSQL avec des données gérées par ArcGIS. Si votre graphe de connaissances utilise un data store NoSQL avec des données gérées par l’utilisateur, différents types de géométrie peuvent être pris en charge.

Les opérateurs spatiaux suivants sont pris en charge :

• ST_Equals - Renvoie les entités avec des géométries égales. La syntaxe à utiliser est esri.graph.ST_Equals(geometry1, geometry2).
• ST_Intersects - Renvoie les entités avec des géométries d’intersection. La syntaxe à utiliser est esri.graph.ST_Intersects(geometry1, geometry2).
• ST_Contains - Renvoie les entités dont les géométries sont contenues dans la géométrie spécifiée. La syntaxe à utiliser est esri.graph.ST_Contains(geometry1, geometry2).

Il est possible d’incorporer des opérateurs spatiaux dans la clause WHERE d’une requête. Les paramètres de géométrie peuvent référencer la géométrie d’une entité, mais vous pouvez spécifier une géométrie qui représente une localisation spatiale. Vous pouvez construire une géométrie à partir d’une chaîne en utilisant l’opérateur esri.graph.ST_WKTToGeometry(string) dont le paramètre de chaîne est une entité simple OGC définie au format Well-Known Text (chaîne de représentation textuelle connue). Par exemple, pour créer une géométrie représentant les coordonnées 117.1964763°W 34.0572046°N, vous devez utiliser l’opérateur esri.graph.ST_WKTToGeometry("POINT (-117.1964763 34.0572046)"). Une géométrie construite ainsi peut être spécifiée uniquement dans le premier argument de géométrie des opérateurs spatiaux. Le second argument de géométrie doit toujours référencer la géométrie associée à une entité du graphe de connaissances.

Voici quelques exemples où les entités de type Person (Personne) peuvent avoir des géométries de point et les entités de type Facility (Ressource) peuvent avoir des géométries de polygone :

• La requête MATCH (p1:Person), (p2:Person) WHERE esri.graph.ST_Equals(p1.shape, p2.shape) RETURN p1, p2 renvoie les entités Person p1 et p2 de formes égales ; les deux entités Person ont donc des géométries de localisation identiques.
• La requête MATCH (e:Employee), (f:Facility) WHERE esri.graph.ST_Intersects(e.shape, f.shape) RETURN e, f renvoie les entités de type Employee (Employé) et Facility (Ressource), respectivement e et f, dont les géométries s’intersectent.
• La requête MATCH (f:Facility) WHERE esri.graph.ST_Contains(esri.graph.ST_WKTToGeometry("POINT (-117.1964763 34.0572046)"), f.shape) RETURN f renvoie les entités de type Facility (Ressource), soit f, dont les géométries contiennent le point spécifié.

Vous avez également à votre disposition l’utilitaire spatial ST_GeoDistance, dont la syntaxe est esri.graph.ST_GeoDistance(geometry, geometry). Cet utilitaire renvoie la distance entre les deux géométries. Par exemple, dans la requête MATCH (n), (e) WHERE esri.graph.ST_GeoDistance(n.shape, e.shape) as distance RETURN n, e, la variable de distance de la clause WHERE stocke la distance géodésique qui est calculée entre les entités n et e.

En savoir plus sur les requêtes openCypher

Vous en saurez plus sur le langage de requête openCypher dans un document fourni par openCypher Implementers Group. ArcGIS Knowledge ne prend pas en charge tous les aspects du langage de requête openCypher. Par exemple, les requêtes ne peuvent pas être utilisées pour mettre à jour le graphe de connaissances, mais uniquement pour renvoyer des valeurs.

Dans ArcGIS Pro, pour en savoir plus sur openCypher, consultez les requêtes qui récupèrent des données à partir d’un graphe de connaissances pour générer des histogrammes. Dans la fenêtre Search and Filter (Rechercher et filtrer), dans l’onglet Histogram (Histogramme) , cliquez sur le bouton Settings (Paramètres) , puis sur Send query to Query tab (Envoyer la requête dans l’onglet Requête). La requête utilisée pour récupérer des données pour l’ensemble d’histogrammes actuel apparaît dans la zone de texte Query (Requête).