GQL-reference (Graph Query Language) til Microsoft Sentinel graph (prøveversion)

Gælder for: Microsoft Sentinel Graph

Denne reference dækker de grundlæggende begreber, funktioner og operatorer for Graph Query Language (GQL). Graph Query Language (GQL) er baseret på matematiske grafteoribegreber, der giver et solidt grundlag for forespørgsler om grafdata. Hvis du forstår disse grundlæggende funktioner, kan du skrive mere effektive forespørgsler og bedre forstå, hvordan GQL behandler dine data. GQL indeholder også et omfattende sæt funktioner og operatorer til at arbejde med grafmønstre, noder, kanter og egenskaber.

Grundlæggende begreber

I dette afsnit beskrives de kernebegreber, der danner grundlaget for grafdataanalyser med GQL.

Grafmønstre

Grafmønstre er kernekomponenterne i GQL-forespørgsler. De beskriver den struktur, du vil finde i dine grafdata, ved hjælp af en deklarativ syntaks, der afspejler den visuelle repræsentation af grafer.

Nodemønstre

Nodemønstre angiver, hvordan de enkelte noder i grafen skal matche:

(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

Vigtige begreber:

• Variabelbinding: (n) Opretter en variabel n, som du kan referere til senere i forespørgslen

• Anonyme noder: (:Person) matcher noder uden at oprette en variabel

• Navnefiltrering: :Person begrænser match til noder med personnavnet

• Navnekombinationer: Bruges & til AND-handlinger | til OR-handlinger

Kantmønstre

Edge-mønstre definerer, hvordan noder opretter forbindelse til hinanden:

-[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) 

Vigtige begreber:

• Retning: -> for udgående, <- for indgående, - for enhver retning

• Kanttyper: Brug navne som :works_at at filtrere efter relationstype

• Flere typer: knows|likes Svarer til begge relationstyper

Navneudtryk

Mærkater giver semantisk betydning for noder og kanter. GQL understøtter komplekse mærkatudtryk:

:Person&Company     -- Both Person AND Company labels 
:Person|Company        -- Person OR Company labels
:!Company               -- NOT Company label
:(Person|!Company)&City -- Complex expressions with parentheses 

Operatører

• & (AND): Noden skal have alle de angivne navne

• | (OR): Noden skal have mindst én angivet etiket

• ! (NOT): Noden må ikke have den angivne etiket

• () : Parenteser til gruppering af komplekse udtryk

Stimønstre

Stimønstre beskriver relationer med flere hop i grafen:

(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 

Stier med variabel længde:

• {2,4}: Præcis 2 til 4 hop

• {1,}: 1 eller flere hop (ubundet). Ubundne stiforespørgsler er begrænset til 8 hop.

• {,5}: Op til 5 hop

• {5}: Præcis 5 hop

Stivariabler

• p=()->(): Henter hele stien til senere analyse

• Få adgang til med NODES(p), , RELATIONSHIPS(p)PATH_LENGTH(p)

Flere mønstre

GQL understøtter komplekse, ikke-lineære grafstrukturer:

(a)->(b), (a)->(c)          -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d)     -- Non-linear structures

Mønstersammensætning:

• Brug kommaer , til at adskille flere mønstre
• Alle mønstre skal matche samtidigt
• Variabler kan deles på tværs af mønstre

Søg efter tilstande

GQL understøtter forskellige tilstande for matchning af stier, der styrer, hvordan mønstre matches i forhold til grafdata. Disse tilstande påvirker ydeevnen, resultatets fuldførelse og de typer stier, der returneres.

Matchtilstande styrer, hvordan grafelementer kan genbruges på tværs af mønstervariabler i en enkelt MATCH-delsætning.

FORSKELLIGE KANTER (standard)

Standardtilstanden. En matchende kant kan ikke binde til mere end én kantvariabel, men noder kan genbruges frit.

MATCH (a)-[r1]->(b)-[r2]->(c) 
-- r1 and r2 must be different edges
-- a, b, c can be the same or different nodes 

ELEMENTER, DER KAN GENTAGES

Gør det muligt at genbruge både kanter og noder på tværs af mønstervariabler uden begrænsninger.

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

Stitilstande

Stitilstande styrer, hvilke typer stier der medtages i resultater baseret på gentagelsesbegrænsninger.

TRAIL

Filtrerer stier, der har gentagne kanter, ud. Noder kan gentages, men hver kant kan kun vises én gang pr. sti.

MATCH TRAIL (a)-[]->{1,3}(b)
-- No edge can appear twice in the same path
-- Nodes may repeat

Reference til funktioner og operatorer

Graph Query Language (GQL) indeholder et omfattende sæt funktioner og operatorer til at arbejde med grafmønstre, noder, kanter og egenskaber.

Centrale GQL-funktioner og -operatorer

I følgende tabel vises de vigtigste GQL-funktioner og -operatorer samt eksempler.

Anbefalede fremgangsmåder

• GQL definerer ikke tydeligt, hvordan dynamiske typer skal håndteres. Hvis du vil undgå kørselsfejl, skal du eksplicit konvertere indlejrede felter til deres forventede type (se CAST).

Optimering af ydeevnen

Brug disse strategier til at optimere ydeevnen af GQL-forespørgsler i produktionsmiljøer:

Begræns stimatchningsområde:

• Brug specifikke navnefiltre til at reducere søgepladsen: MATCH (start:SpecificType) i stedet for MATCH (start)

• Begræns variable længdestier med rimelige grænser: MATCH (a)-[]->{1,3}(b) i stedet for ubundne stier

• Anvend WHERE-delsætninger tidligt for at filtrere resultater før dyre handlinger.

Brug COUNT(*) til kontrol af eksistens:

Hvis du kun har brug for at kontrollere, om der findes et mønster, skal du bruge COUNT(*) i stedet for at returnere fulde resultater.

MATCH (user:User)-[:SUSPICIOUS_ACTIVITY]->(target)
WHERE user.id = 'user123'
RETURN COUNT(*) > 0 AS HasSuspiciousActivity

Begrænsninger

• Forespørgselsstruktur: Alle GQL-forespørgsler skal starte med en MATCH-sætning.

• Reserverede nøgleord: Nogle GQL-nøgleord kan ikke bruges som identifikatorer i forespørgsler. Nogle reserverede nøgleord er ikke umiddelbart indlysende (f.eks. er DATE et reserveret nøgleord). Hvis dine grafdata har egenskabsnavne, der er i konflikt med reserverede GQL-nøgleord, kan du bruge forskellige egenskabsnavne i grafskemaet eller omdøbe dem for at undgå fortolkningskonflikter.

• Ingen INSERT/CREATE-understøttelse: Handlinger til ændring af grafstrukturer understøttes ikke.

• Valgfrie matches: Understøttes kun for nodemønstre (ikke kanter).

• Kontroller af enhedsækvivalens understøttes ikke: GQL-objekter (MATCH (n)-[]-(n2) WHERE n1 <> n2) understøttes ikke. Brug eksplicitte feltsammenligninger i stedet, f.eks. n.id <> n2.id

• Tid og tidszone: Motoren arbejder i UTC. Datetime-konstanter skal bruge zoned datetime. Kun UTC-zonen understøttes via ZONED_DATETIME("2011-12-31 23:59:59.9").

• Varighedsgranularitet: Varigheder understøtter op til dage og mindre enheder ned til nanosekunder. Enheder, der er større end dage (f.eks. uger, måneder og år), understøttes ikke.

Labels() brugerdefineret GQL-funktion

Funktionen labels() viser mærkaterne for en node eller kant som en matrix.

Syntaks:

labels(entity)

Parametre:entity: En node- eller kantvariabel fra et matchende mønster.

Returnerer:

Returnerer en matrix af strenge med alle navne for den angivne enhed.

Eksempler:

Vis navne for matchede noder:

MATCH (entity)
RETURN entity.name, labels(entity)

Output

Denne forespørgsel viser navnet og alle mærkater for hver node i grafen.

Vis navne i projektioner med aliasser:

MATCH (n)-[e]->(target)
RETURN n.name, labels(n) AS n_labels, labels(e) AS edge_labels, target.name

Denne forespørgsel viser nodenavne, deres navne og etiketterne for forbundne kanter.