Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
S’applique à : Microsoft Sentinel Graph
Remarque
La prise en charge de GQL est en préversion. Les fonctionnalités et la syntaxe peuvent changer en fonction des commentaires et du développement en cours.
Cette référence couvre les concepts fondamentaux, les fonctions et les opérateurs du langage GQL (Graph Query Language). Le langage de requête de graphe (GQL) repose sur des concepts mathématiques de la théorie des graphes qui fournissent une base solide pour l’interrogation des données de graphe. La compréhension de ces principes fondamentaux vous permet d’écrire des requêtes plus efficaces et de mieux comprendre comment GQL traite vos données. GQL fournit également un ensemble complet de fonctions et d’opérateurs pour travailler avec des modèles de graphe, des nœuds, des arêtes et des propriétés.
Concepts fondamentaux
Cette section décrit les concepts fondamentaux qui constituent la base de l’analyse des données de graphe avec GQL.
Modèles de graphe
Les modèles de graphe sont les principaux blocs de construction des requêtes GQL. Ils décrivent la structure que vous souhaitez trouver dans vos données de graphe à l’aide d’une syntaxe déclarative qui reflète la représentation visuelle des graphiques.
Modèles de nœud
Les modèles de nœud spécifient comment faire correspondre des nœuds individuels dans votre graphe :
(n) -- Any node
(n:Person) -- Node with Person label
(n:Person&City) -- Node with Person AND City label
(:Person) -- Person node, don't bind variable
Concepts clés :
Liaison de variable :
(n)crée une variable n que vous pouvez référencer ultérieurement dans la requêteNœuds anonymes :
(:Person)correspond aux nœuds sans créer de variableFiltrage des étiquettes :
:Personlimite les correspondances aux nœuds avec l’étiquette PersonCombinaisons d’étiquettes : utiliser
&pour AND,|pour les opérations OR
Modèles d’arête
Les modèles de périphérie définissent la façon dont les nœuds se connectent les uns aux autres :
-[e]-> -- Directed outgoing edge, any label
-[e:works_at]-> -- Directed edge, works_at label
-[e:knows|likes]--> -- knows OR likes edge
<-[e]- -- Directed incoming edge
-[e]- -- Undirected (any direction)
Concepts clés :
Direction :
->pour sortant,<-entrant,-pour n’importe quelle directionTypes d’arêtes : utilisez des étiquettes comme
:works_atpour filtrer par type de relationPlusieurs types :
knows|likescorrespond à l’un ou l’autre type de relation
Expressions d’étiquette
Les étiquettes fournissent une signification sémantique aux nœuds et aux arêtes. GQL prend en charge les expressions d’étiquette complexes :
:Person&Company -- Both Person AND Company labels
:Person|Company -- Person OR Company labels
:!Company -- NOT Company label
:(Person|!Company)&City -- Complex expressions with parentheses
Opérateurs
&(AND) : le nœud doit avoir toutes les étiquettes spécifiées|(OR) : le nœud doit avoir au moins une étiquette spécifiée!(NOT) : le nœud ne doit pas avoir l’étiquette spécifiée(): parenthèses pour le regroupement d’expressions complexes
Modèles de chemin d’accès
Les modèles de chemin d’accès décrivent les relations à plusieurs tronçons dans votre graphe :
(a)-[e1]->;(b)-[e2]->(c) -- 2-hop path
(a)-[e]->;{2,4}(b) -- 2 to 4 hops
(a)-[e]->{1,}(b) -- 1 to maximum of 8 hops
(a)-[:knows|likes]->;{1,3}(b) -- 1-3 hops via knows/likes
p=()-[:works_at]->() -- Binding a path variable
Chemins d’accès de longueur variable :
{2,4}: Exactement 2 à 4 tronçons{1,}: 1 ou plusieurs tronçons (sans limite). Les requêtes de chemin d’accès illimité sont limitées à 8 tronçons.{,5}: Jusqu’à 5 tronçons{5}: Exactement 5 tronçons
Variables de chemin d’accès
p=()->(): capture l’intégralité du chemin d’accès pour une analyse ultérieureAccès avec
NODES(p),RELATIONSHIPS(p),PATH_LENGTH(p)
Modèles multiples
GQL prend en charge les structures de graphe complexes et non linéaires :
(a)->(b), (a)->(c) -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d) -- Non-linear structures
Composition du modèle :
- Utiliser des virgules
,pour séparer plusieurs modèles - Tous les modèles doivent correspondre simultanément
- Les variables peuvent être partagées entre des modèles
Modes de correspondance
GQL prend en charge différents modes de correspondance de chemin qui contrôlent la façon dont les modèles sont mis en correspondance avec les données de graphique. Ces modes affectent les performances, l’exhaustivité des résultats et les types de chemins d’accès retournés.
Les modes de correspondance contrôlent la façon dont les éléments de graphe peuvent être réutilisés dans les variables de modèle au sein d’une seule clause MATCH.
DIFFERENT EDGES (par défaut)
Mode par défaut. Une arête correspondante ne peut pas être liée à plusieurs variables d’arête, mais les nœuds peuvent être réutilisés librement.
MATCH (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 must be different edges
-- a, b, c can be the same or different nodes
ÉLÉMENTS REPRODUCTIBLES
Permet la réutilisation des arêtes et des nœuds entre des variables de modèle sans restrictions.
MATCH REPEATABLE ELEMENTS (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 can be the same edge
-- a, b, c can be the same or different nodes
Modes de chemin d’accès
Les modes de chemin contrôlent les types de chemins inclus dans les résultats en fonction des contraintes de répétition.
SENTIER
Filtre les chemins qui ont des arêtes répétées. Les nœuds peuvent se répéter, mais chaque bord ne peut apparaître qu’une seule fois par chemin.
MATCH TRAIL (a)-[]->{1,3}(b)
-- No edge can appear twice in the same path
-- Nodes may repeat
Informations de référence sur les fonctions et les opérateurs
Le langage GQL (Graph Query Language) fournit un ensemble complet de fonctions et d’opérateurs pour travailler avec des modèles de graphe, des nœuds, des arêtes et des propriétés.
Principales fonctions et opérateurs GQL
Le tableau suivant répertorie les principales fonctions et opérateurs GQL, ainsi que des exemples.
| GQL, fonction/opérateur | Description | Exemple GQL |
|---|---|---|
| MATCH | Rechercher des modèles de graphe | MATCH (a)-[r]->(b) |
| CORRESPONDANCE FACULTATIVE | Rechercher des modèles qui n’existent peut-être pas | OPTIONAL MATCH (p)->(c :City) |
| WHERE | Modèles et propriétés de filtre | WHERE person.age > 25 ans |
| FILTER | Équivalent à WHERE, mais utilisé sans clauses MATCH | FILTER p.name = 'Carol' OR c.name = 'Seattle' |
| EST NULL | Rechercher des valeurs Null | WHERE person.age IS NULL |
| N’EST PAS NULL | Rechercher des valeurs non null | WHERE person.age IS NOT NULL |
| RETOUR | Résultats du projet | RETOUR person.name, person.age |
| DISTINCTES | Retourner des valeurs uniques | RETURN DISTINCT person.name |
| COUNT(*) | Compter toutes les lignes | NOMBRE DE RETOURS(*) |
| COUNT() | Compter les valeurs non null | RETURN COUNT(person.name) |
| SUM() | Total des valeurs numériques | RETURN SUM(person.age) |
| MIN() | Valeur minimale | RETURN MIN(person.age) |
| MAX() | Valeur maximale | RETURN MAX(person.age) |
| AVG() | Valeur moyenne | RETURN AVG(person.age) |
| COLLECT_LIST() | Collecter des valeurs dans un tableau | RETOUR COLLECT_LIST(person.name) |
| SIZE() | Longueur du tableau | RETURN SIZE(COLLECT_LIST(n.firstName)) |
| labels() | Afficher les étiquettes d’un nœud ou d’une arête | RETURN labels(entity) |
| UPPER() | Convertir en majuscules | RETOUR UPPER(person.name) |
| LOWER() | Convertir en minuscules | RETURN LOWER(person.name) |
| COMMENCE PAR | La chaîne commence par le modèle | OÙ person.name COMMENCE PAR « Tom » |
| SE TERMINE PAR | La chaîne se termine par le modèle | OÙ person.name SE TERMINE PAR 'Hanks' |
| CONTAINS | Chaîne contient le modèle | WHERE person.name CONTAINS 'Tom' |
| || | Concaténation de chaînes | RETURN n.firstName || ' ' || n.lastName |
| TRIM() | Supprimer les espaces blancs des deux extrémités | RETURN TRIM(' abc ') |
| STRING_JOIN() | Joindre des éléments de tableau avec un délimiteur | RETURN STRING_JOIN(["a », « b » || « c"], « -« ) |
| CAST() | Convertir des types de données | CAST(person.age AS STRING) |
| ZONED_DATETIME() | Créer datetime à partir d’une chaîne | ZONED_DATETIME('2024-01-01') |
| PATH_LENGTH() | Obtenir la longueur d’un chemin d’accès | RETOUR PATH_LENGTH(path_variable) |
| TRIER PAR | Critère de tri des éléments | ORDER BY person.age DESC |
| LIMITE | Limiter le nombre de résultats | LIMITE 10 |
| & (AND) | Intersection des étiquettes | MATCH (p :Person & Mâle) |
| | (OR) | Union d’étiquettes | MATCH (n :Person | Film) |
| ! (NOT) | Négation des étiquettes | MATCH (p :! Femelle) |
Meilleures pratiques
- GQL ne définit pas clairement comment les types dynamiques doivent être gérés. Pour éviter les erreurs d’exécution, cassez explicitement les champs imbriqués en leur type attendu (voir CAST).
Optimisation des performances
Utilisez ces stratégies pour optimiser les performances des requêtes GQL dans les environnements de production :
Conseil
Commencez par des modèles simples, puis augmentez la complexité si nécessaire. Surveillez les performances des requêtes et ajustez la longueur des chemins et les filtres pour améliorer les résultats.
Limitez l’étendue de correspondance de chemin d’accès :
Utilisez des filtres d’étiquettes spécifiques pour réduire l’espace de recherche : MATCH (start :SpecificType) au lieu de MATCH (start)
Limiter les chemins d’accès de longueur variable avec des limites raisonnables : MATCH (a)-[]->{1,3}(b) au lieu de chemins non limités
Appliquez les clauses WHERE tôt pour filtrer les résultats avant les opérations coûteuses.
Utilisez COUNT(*) pour les vérifications d’existence :
Si vous devez uniquement case activée si un modèle existe, utilisez COUNT(*) au lieu de retourner des résultats complets.
MATCH (user:User)-[:SUSPICIOUS_ACTIVITY]->(target)
WHERE user.id = 'user123'
RETURN COUNT(*) > 0 AS HasSuspiciousActivity
Limitations
Structure de requête : toutes les requêtes GQL doivent commencer par une instruction MATCH.
Mots clés réservés : certains mots clés GQL ne peuvent pas être utilisés comme identificateurs dans les requêtes. Certains mots clés réservés ne sont pas immédiatement évidents (par exemple, DATE est un mot clé réservé). Si vos données de graphe ont des noms de propriétés qui entrent en conflit avec des mots clés réservés GQL, utilisez des noms de propriétés différents dans votre schéma de graphe ou renommez-les pour éviter les conflits d’analyse.
Importante
Lorsque vous concevez votre schéma de graphe, certains noms de propriétés courants peuvent entrer en conflit avec les mots clés réservés GQL. Évitez ou renommez ces noms de propriétés.
Aucune prise en charge INSERT/CREATE : les opérations de modification des structures de graphe ne sont pas prises en charge.
Correspondances facultatives : prise en charge uniquement pour les modèles de nœud (et non pour les arêtes).
Vérifications d’équivalence d’entité non prises en charge : les contrôles GQL ne
(MATCH (n)-[]-(n2) WHERE n1 <> n2)sont pas pris en charge. Utilisez plutôt des comparaisons de champs explicites, par exemplen.id <> n2.idHeure et fuseau horaire : le moteur fonctionne au format UTC. Les littéraux datetime doivent utiliser une datetime interzone ; seule la zone UTC est prise en charge via
ZONED_DATETIME("2011-12-31 23:59:59.9").Granularité de la durée : les durées prennent en charge jusqu’à des jours et des unités plus petites jusqu’à nanosecondes. Les unités supérieures à un jour (par exemple, semaines, mois, années) ne sont pas prises en charge.
Étiquettes() fonction GQL personnalisée
La labels() fonction affiche les étiquettes d’un nœud ou d’une arête sous forme de tableau.
Syntaxe :
labels(entity)
Paramètres :entity variable de nœud ou d’arête à partir d’un modèle correspondant.
Retourne:
Retourne un tableau de chaînes avec toutes les étiquettes de l’entité spécifiée.
Exemples :
Afficher les étiquettes des nœuds correspondants :
MATCH (entity)
RETURN entity.name, labels(entity)
Résultat
Cette requête affiche le nom et toutes les étiquettes de chaque nœud dans le graphique.
| entity.name | labels(entity) |
|---|---|
| john.doe | ["User"] |
| admin.user | ["User"] |
| serveur web | ["System"] |
| Base | ["System"] |
| contrôleur de domaine | ["System"] |
Afficher les étiquettes dans les projections avec des alias :
MATCH (n)-[e]->(target)
RETURN n.name, labels(n) AS n_labels, labels(e) AS edge_labels, target.name
Cette requête affiche les noms des nœuds, leurs étiquettes et les étiquettes des arêtes de connexion.
| n.name | n_labels | edge_labels | target.name |
|---|---|---|---|
| john.doe | ["User"] | ["CAN_ACCESS"] | serveur web |
| admin.user | ["User"] | ["CAN_ACCESS"] | contrôleur de domaine |
| serveur web | ["System"] | ["CAN_ACCESS"] | Base |
| contrôleur de domaine | ["System"] | ["CAN_ACCESS"] | Base |