Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Gilt für: Microsoft Sentinel Graph
Hinweis
Die GQL-Unterstützung befindet sich in der Vorschauphase. Features und Syntax können sich basierend auf Feedback und laufender Entwicklung ändern.
In dieser Referenz werden die grundlegenden Konzepte, Funktionen und Operatoren der Graph Query Language (GQL) behandelt. Graph Query Language (GQL) basiert auf mathematischen Graphtheoriekonzepten, die eine solide Grundlage für das Abfragen von Graphdaten bieten. Wenn Sie diese Grundlagen verstehen, können Sie effektivere Abfragen schreiben und besser verstehen, wie GQL Ihre Daten verarbeitet. GQL bietet auch eine Vielzahl von Funktionen und Operatoren für die Arbeit mit Diagrammmustern, Knoten, Kanten und Eigenschaften.
Grundlegende Konzepte
In diesem Abschnitt werden die wichtigsten Konzepte behandelt, die die Grundlage der Graphdatenanalyse mit GQL bilden.
Diagrammmuster
Graphmuster sind die wichtigsten Bausteine von GQL-Abfragen. Sie beschreiben die Struktur, die Sie in Ihren Graphdaten finden möchten, indem sie eine deklarative Syntax verwenden, die die visuelle Darstellung von Diagrammen widerspiegelt.
Knotenmuster
Knotenmuster geben an, wie einzelne Knoten in Ihrem Graphen zugeordnet werden sollen:
(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
Wichtige Konzepte:
Variablenbindung:
(n)Erstellt eine Variable n, auf die Sie später in der Abfrage verweisen können.Anonyme Knoten:
(:Person)Gleicht Knoten ab, ohne eine Variable zu erstellen.Bezeichnungsfilterung:
:PersonSchränkt Übereinstimmungen auf Knoten mit der Personenbezeichnung ein.Bezeichnungskombinationen: Verwenden Sie
&für AND,|für OR-Vorgänge
Kantenmuster
Edgemuster definieren, wie Knoten eine Verbindung miteinander herstellen:
-[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)
Wichtige Konzepte:
Richtung:
->für ausgehend,<-für eingehende,-für jede RichtungEdgetypen: Verwenden Von Bezeichnungen wie
:works_atzum Filtern nach BeziehungstypMehrere Typen:
knows|likesEntspricht einem der beiden Beziehungstypen.
Bezeichnungsausdrücke
Bezeichnungen bieten Knoten und Kanten eine semantische Bedeutung. GQL unterstützt komplexe Bezeichnungsausdrücke:
:Person&Company -- Both Person AND Company labels
:Person|Company -- Person OR Company labels
:!Company -- NOT Company label
:(Person|!Company)&City -- Complex expressions with parentheses
Operatoren
&(AND): Knoten muss über alle angegebenen Bezeichnungen verfügen|(OR): Der Knoten muss mindestens eine angegebene Bezeichnung aufweisen.!(NOT): Der Knoten darf nicht über die angegebene Bezeichnung verfügen.(): Klammern zum Gruppieren komplexer Ausdrücke
Pfadmuster
Pfadmuster beschreiben Multi-Hop-Beziehungen in Ihrem Diagramm:
(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
Pfade variabler Länge:
{2,4}: Genau 2 bis 4 Hops{1,}: 1 oder mehr Hops (ungebunden). Ungebundene Pfadabfragen sind auf 8 Hops beschränkt.{,5}: Bis zu 5 Hops{5}: Genau 5 Hops
Pfadvariablen
p=()->(): Erfasst den gesamten Pfad für eine spätere Analyse.Zugriff mit
NODES(p),RELATIONSHIPS(p),PATH_LENGTH(p)
Mehrere Muster
GQL unterstützt komplexe, nicht lineare Graphstrukturen:
(a)->(b), (a)->(c) -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d) -- Non-linear structures
Musterkomposition:
- Verwenden von Kommas
,zum Trennen mehrerer Muster - Alle Muster müssen gleichzeitig übereinstimmen.
- Variablen können musterübergreifend gemeinsam verwendet werden.
Übereinstimmungsmodi
GQL unterstützt verschiedene Pfadabgleichsmodi, die steuern, wie Muster mit Graphdaten abgeglichen werden. Diese Modi wirken sich auf die Leistung, die Vollständigkeit des Ergebnisses und die Typen von Pfaden aus, die zurückgegeben werden.
Übereinstimmungsmodi steuern, wie Graphelemente für Mustervariablen innerhalb einer einzelnen MATCH-Klausel wiederverwendet werden können.
DIFFERENT EDGES (Standard)
Der Standardmodus. Ein abgeglichener Edge kann nicht an mehrere Edgevariablen gebunden werden, Knoten können jedoch frei wiederverwendet werden.
MATCH (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 must be different edges
-- a, b, c can be the same or different nodes
WIEDERHOLBARE ELEMENTE
Ermöglicht die Wiederverwendung von Kanten und Knoten über Mustervariablen hinweg ohne Einschränkungen.
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
Pfadmodi
Pfadmodi steuern basierend auf Wiederholungseinschränkungen, welche Pfadtypen in Ergebnissen enthalten sind.
WEG
Filtert Pfade mit wiederholten Kanten heraus. Knoten können sich wiederholen, aber jeder Edge kann nur einmal pro Pfad angezeigt werden.
MATCH TRAIL (a)-[]->{1,3}(b)
-- No edge can appear twice in the same path
-- Nodes may repeat
Referenz zu Funktionen und Operatoren
Graph Query Language (GQL) bietet eine Vielzahl von Funktionen und Operatoren zum Arbeiten mit Diagrammmustern, Knoten, Kanten und Eigenschaften.
Grundlegende GQL-Funktionen und -Operatoren
In der folgenden Tabelle sind die wichtigsten GQL-Funktionen und -Operatoren sowie Beispiele aufgeführt.
| GQL-Funktion/Operator | Beschreibung | GQL-Beispiel |
|---|---|---|
| MATCH | Suchen von Diagrammmustern | MATCH (a)-[r]->(b) |
| OPTIONALE ÜBEREINSTIMMUNG | Suchen nach Mustern, die möglicherweise nicht vorhanden sind | OPTIONAL MATCH (p)->(c:City) |
| WHERE | Filtern von Mustern und Eigenschaften | WHERE person.age > 25 |
| FILTER | Entspricht WHERE, wird jedoch ohne MATCH-Klauseln verwendet. | FILTER p.name = 'Carol' OR c.name = 'Seattle' |
| IS NULL | Überprüfen auf NULL-Werte | WHERE person.age IS NULL |
| IST NICHT NULL | Überprüfen auf Werte ungleich NULL | WHERE person.age IS NOT NULL |
| EINGABETASTE | Projektergebnisse | RETURN person.name, person.age |
| UNTERSCHIEDLICHE | Zurückgeben eindeutiger Werte | RETURN DISTINCT person.name |
| ANZAHL(*) | Alle Zeilen zählen | RETURN COUNT(*) |
| COUNT() | Zählen von Nicht-NULL-Werten | RETURN COUNT(person.name) |
| SUMME() | Summieren numerischer Werte | RETURN SUM(person.age) |
| MIN() | Kleinster Wert | RETURN MIN(person.age) |
| MAX() | Maximalwert | RETURN MAX(person.age) |
| AVG() | Durchschnittswert | RETURN AVG(person.age) |
| COLLECT_LIST() | Sammeln von Werten im Array | RETURN COLLECT_LIST(person.name) |
| SIZE() | Arraylänge | RETURN SIZE(COLLECT_LIST(n.firstName)) |
| labels() | Anzeigen von Bezeichnungen für einen Knoten oder Edge | RETURN labels(entity) |
| UPPER() | Konvertieren in Großbuchstaben | RETURN UPPER(person.name) |
| LOWER() | Konvertieren in Kleinbuchstaben | RETURN LOWER(person.name) |
| BEGINNT MIT | Zeichenfolge beginnt mit Muster | WHERE person.name BEGINNT MIT 'Tom' |
| ENDET MIT | Zeichenfolge endet mit Muster | WHERE person.name ENDET MIT 'Hanks' |
| CONTAINS | Zeichenfolge enthält Muster | WHERE person.name CONTAINS 'Tom' |
| || | Zeichenfolgenverknüpfung | RETURN n.firstName || ' ' || n.lastName |
| TRIM() | Leerzeichen von beiden Enden entfernen | RETURN TRIM(' abc ') |
| STRING_JOIN() | Verbinden von Arrayelementen mit Trennzeichen | RETURN STRING_JOIN(["a", "b" || "c"], "-") |
| CAST() | Konvertieren von Datentypen | CAST(person.age AS STRING) |
| ZONED_DATETIME() | Erstellen von datetime aus einer Zeichenfolge | ZONED_DATETIME('2024-01-01') |
| PATH_LENGTH() | Abrufen der Länge eines Pfads | RETURN PATH_LENGTH(path_variable) |
| ORDNEN NACH | Ergebnisse sortieren | ORDER BY person.age DESC |
| LIMIT | Einschränken der Ergebnisanzahl | LIMIT 10 |
| & (AND) | Bezeichnungs-Schnittmenge | MATCH (p:Person & Männlich) |
| | (ODER) | Bezeichnungsunion | MATCH (n:Person | Film) |
| ! (NICHT) | Bezeichnungs negation | MATCH (p:! Weiblich) |
Bewährte Methoden
- GQL definiert nicht eindeutig, wie dynamische Typen behandelt werden sollen. Um Laufzeitfehler zu vermeiden, wandeln Sie geschachtelte Felder explizit in ihren erwarteten Typ um (siehe CAST).
Leistungsoptimierung
Verwenden Sie diese Strategien, um die Leistung von GQL-Abfragen in Produktionsumgebungen zu optimieren:
Tipp
Beginnen Sie mit einfachen Mustern, und erhöhen Sie dann bei Bedarf die Komplexität. Überwachen Sie die Abfrageleistung, und passen Sie Pfadlängen und Filter an, um die Ergebnisse zu verbessern.
Pfadabgleichsbereich einschränken:
Verwenden Sie bestimmte Bezeichnungsfilter, um den Suchraum zu reduzieren: MATCH (start:SpecificType) anstelle von MATCH (start)
Einschränken von Pfaden mit variabler Länge mit angemessenen Grenzen: ÜBEREINSTIMMUNG (a)-[]->{1,3}(b) anstelle von ungebundenen Pfaden
Wenden Sie WHERE-Klauseln frühzeitig an, um Ergebnisse vor teuren Vorgängen zu filtern.
Verwenden Sie COUNT(*) für Existenzüberprüfungen:
Wenn Sie nur überprüfen müssen, ob ein Muster vorhanden ist, verwenden Sie COUNT(*), anstatt vollständige Ergebnisse zurückzugeben.
MATCH (user:User)-[:SUSPICIOUS_ACTIVITY]->(target)
WHERE user.id = 'user123'
RETURN COUNT(*) > 0 AS HasSuspiciousActivity
Begrenzungen
Abfragestruktur: Alle GQL-Abfragen müssen mit einer MATCH-Anweisung beginnen.
Reservierte Schlüsselwörter: Einige GQL-Schlüsselwörter können nicht als Bezeichner in Abfragen verwendet werden. Einige reservierte Schlüsselwörter sind nicht sofort offensichtlich (z. B. ist DATE eine reservierte Schlüsselwort (keyword)). Wenn Ihre Graphdaten Eigenschaftennamen haben, die mit reservierten GQL-Schlüsselwörtern in Konflikt treten, verwenden Sie andere Eigenschaftsnamen in Ihrem Graphschema, oder benennen Sie sie um, um Analysekonflikte zu vermeiden.
Wichtig
Wenn Sie Ihr Graphschema entwerfen, können einige allgemeine Eigenschaftsnamen mit reservierten GQL-Schlüsselwörtern in Konflikt geraten. Vermeiden Sie diese Eigenschaftsnamen, oder benennen Sie sie um.
Keine INSERT/CREATE-Unterstützung: Vorgänge zum Ändern von Graphstrukturen werden nicht unterstützt.
Optionale Übereinstimmungen: Wird nur für Knotenmuster (keine Kanten) unterstützt.
Entitätsäquivalenzprüfungen werden nicht unterstützt: GQL-Überprüfungen
(MATCH (n)-[]-(n2) WHERE n1 <> n2)werden nicht unterstützt. Verwenden Sie stattdessen explizite Feldvergleiche, z. B.n.id <> n2.idUhrzeit und Zeitzone: Die Engine arbeitet in UTC. Datetime-Literale müssen "datetime"-Zonen verwenden. nur die UTC-Zone wird über
ZONED_DATETIME("2011-12-31 23:59:59.9")unterstützt.Granularität der Dauer: Daueren unterstützen bis zu Tage und kleinere Einheiten bis zu Nanosekunden. Größere Einheiten als Tageseinheiten (z. B. Wochen, Monate, Jahre) werden nicht unterstützt.
Benutzerdefinierte GQL-Funktion "Labels()"
Die labels() Funktion zeigt die Bezeichnungen für einen Knoten oder edge als Array an.
Syntax:
labels(entity)
Parameter:entity: Ein Knoten oder eine Edgevariable aus einem übereinstimmend muster.
Gibt:
Gibt ein Array von Zeichenfolgen mit allen Bezeichnungen für die angegebene Entität zurück.
Beispiele:
Anzeigen von Bezeichnungen für übereinstimmene Knoten:
MATCH (entity)
RETURN entity.name, labels(entity)
Ausgabe
Diese Abfrage zeigt den Namen und alle Bezeichnungen für jeden Knoten im Diagramm an.
| entity.name | labels(entity) |
|---|---|
| john.doe | ["Benutzer"] |
| admin.user | ["Benutzer"] |
| Webserver | ["System"] |
| Datenbank | ["System"] |
| Domänencontroller | ["System"] |
Anzeigen von Bezeichnungen in Projektionen mit Aliasen:
MATCH (n)-[e]->(target)
RETURN n.name, labels(n) AS n_labels, labels(e) AS edge_labels, target.name
Diese Abfrage zeigt Knotennamen, deren Bezeichnungen und die Bezeichnungen von Verbindungskanten an.
| n.name | n_labels | edge_labels | target.name |
|---|---|---|---|
| john.doe | ["Benutzer"] | ["CAN_ACCESS"] | Webserver |
| admin.user | ["Benutzer"] | ["CAN_ACCESS"] | Domänencontroller |
| Webserver | ["System"] | ["CAN_ACCESS"] | Datenbank |
| Domänencontroller | ["System"] | ["CAN_ACCESS"] | Datenbank |