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

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 stocker les données temporelles avec ArcGIS Enterprise 11.2 et les versions ultérieures de différentes manières. Lorsque vous stockez et interrogez des données temporelles, vous devez prendre en compte l’emplacement des événements et celui des personnes qui accèdent aux données.

Si vous stockez des données locales et les utilisez dans la même zone, vous pouvez stocker les informations de date et d’heure sans vous préoccuper du fuseau horaire. Ces données peuvent être stockées dans les propriétés avec le type de données date. Si les données proviennent d’autres fuseaux horaires ou sont interrogés à partir d’autres fuseaux horaires, vous devez veiller à ce que les valeurs correctes soient stockées et interrogées, quels que soient vos localisation et fuseau horaire. Les propriétés dont le type de données est Timestamp offset (Décalage de l’horodatage) vous permettent d’enregistrer des valeurs de date-heure qui prennent en compte les fuseaux horaires de l’événement et des données utilisées.

Vous pouvez accéder aux valeur de date et d’heure stockées dans le graphe de connaissances à l’aide d’une requête openCypher. Pour obtenir les résultats corrects, vous devez utiliser des fonctions spécifiques pour interroger les propriétés de chaque type de données, comme décrit dans le tableau ci après. L’utilisation d’autres fonctions peut entraîner une erreur ou des résultats inattendus. Si des valeurs temporelles sont fournies à la requête ou renvoyées par cette dernière, elles utilisent toujours le format de date-heure ISO 8601.

Type de champ	fonction	Syntaxe	Exemple
Date	localdatetime()	localdatetime('YYYY-MM-DDThh:mm:ss.sss')	localdatetime('2015-07-24T21:40:53.142')
Date uniquement	date()	date('YYYY-MM-DD')	date('2015-07-24')
Heure uniquement	localtime()	localtime('hh:mm:ss.sss')	localtime('21:40:53.142')
Décalage de l’horodatage	datetime()	datetime('YYYY-MM-DDThh:mm:ss.sssZ') ou datetime('YYYY-MM-DDThh:mm:ss.sss+00:00')	datetime('2015-07-24T21:40:53.142Z') ou datetime('2015-07-21T21:40:53.142-08:00')

Pour évaluer une propriété de graphe de connaissance dont le type de données est Timestamp offset (Décalage de l’horodatage), utilisez la fonction datetime() dans votre requête openCypher. Utilisez le format date-heure YYYY-MM-DDThh:mm:ss.sssZ si la valeur spécifiée est exprimée en temps universel coordonné (UTC). Utilisez le format YYYY-MM-DDThh:mm:ss.sss+00:00 si la valeur correspond à une date en heure locale avec le décalage horaire approprié. S’il manque des parties importantes dans la valeur date-heure fournie dans la requête, cette dernière 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.

Depuis ArcGIS Enterprise 11.3, une requête openCypher peut accéder aux valeurs temporelles du graphe de connaissances à l’aide de durées. Cela vous permet de comprendre les différences de temps entre les points de données. Vous pouvez rechercher les entités et relations où les événements capturés dans leurs propriétés durent pendant un certain temps ou pour lesquelles un délai donné s’écoule entre les événements.

Si une durée est fournie à la requête ou renvoyée par cette dernière, elle utilise toujours le format de durée ISO 8601. Par exemple, une durée de P1Y2M3DT4H5M6S représente un intervalle temporel d’un an, deux mois, trois jours, quatre heures, cinq minutes et six secondes. Des portions de la durée peuvent être ignorées si leur valeur est nulle. Par exemple, une période d’un jour et demi peut être représentée sous la forme P1DT12H ou PT36H. Si la chaîne de durée inclut une composante heure, le caractère T doit être spécifié entre les composantes date et heure.

Vous pouvez utiliser plusieurs fonctions de durée pour calculer la période entre deux horaires, comme décrit ci après. La durée peut être exprimée dans des unités de temps spécifiques, si nécessaire.

• duration.between(a, b) : temps écoulé entre les heures a et b. Une durée spécifiant le délai total écoulé en années, mois, jours etc. est renvoyée.
• duration.inMonths(a, b) : le temps écoulé entre les heures a et b est calculé en nombre de mois entiers et renvoyé comme durée. Les durées inférieures à un mois complet sont ignorées.
• duration.inDays(a, b) : le temps écoulé entre les heures a et b est calculé en nombre de jours entiers et renvoyé comme durée. Les durées inférieures à un jour complet sont ignorées.
• duration.inSeconds(a, b) : le temps écoulé entre les heures a et b est calculé en nombre de secondes entières et renvoyé comme durée. Les durées inférieures à une seconde complète sont ignorées.

Par exemple, pour rechercher les personnes ayant vendu un véhicule à leur nom depuis moins de deux ans, utilisez une requête telle que la suivante : MATCH path=(:Person)-[hv:HasVehicle]->(:Vehicle) WHERE hv.endDate < (hv.acquisitionDate + duration('P2Y')) RETURN path, duration.between(hv.acquisitionDate,hv.endDate) as TimeOwned. Tous les chemins renvoyés coïncident avec une relation HasVehicle possédant la propriété endDate où la durée entre les propriétés endDate et acquisitionDate est inférieure à deux ans. La requête renvoie à la fois le chemin et la durée de possession du véhicule.

Lorsque vous calculez une durée, vous pouvez spécifier la date du jour où l’heure actuelle comme l’un des deux moments, en spécifiant une fonction date-heure à l’endroit approprié. Toutes les portions de la durée sont accessibles et peuvent être renvoyées ou utilisées dans la requête. L’exemple suivant identifie les personnes ayant acheté un véhicule il y a plus de quatre ans : MATCH path=(:Person)-[hv:HasVehicle]->(:Vehicle) WHERE duration.between(hv.acquisitionDate, datetime()).years > 4 RETURN path. Les date et heure actuelles sont utilisées dans la requête en spécifiant la fonction datetime() sans préciser de date spécifique. Le système accède alors à la portion année de la durée calculée et l’évalue pour rechercher les chemins appropriés. Toutes les portions de la durée (jours, heures, minutes etc.) sont accessibles de cette manière.

Il est également possible de calculer les durées entre des événements qui se produisent entre les parties liées. Par exemple, la requête ci-après évalue un graphe de connaissance pour déterminer la relation entre les entités Phone (Téléphone) et les relations appelées et le temps écoulé entre les appels téléphoniques : MATCH (:Phone)-[c1:Called]-(:Phone)-[c2:Called]-(:Phone) WHERE duration.between(c1.datecalled, c2.datecalled).minutes < 45 RETURN c1, c2. Dans cette requête, une durée est calculée entre les moments où un téléphone reçoit un appel et place un deuxième appel. Le système accède à la propriété minutes de la durée et, si moins de 45 minutes se sont écoulées entre les appels, les premier et deuxième appels téléphoniques sont renvoyés par la requête.

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 utiliser les informations stockées dans les enregistrements de provenance dans votre 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).