GQL-referens (Graph Query Language) för Microsoft Sentinel diagram (förhandsversion)

Gäller för: Microsoft Sentinel Graph

Obs!

GQL-stöd finns i förhandsversion. Funktioner och syntax kan ändras baserat på feedback och pågående utveckling.

Den här referensen beskriver de grundläggande begreppen, funktionerna och operatorerna för Graph Query Language (GQL). Graph Query Language (GQL) bygger på matematiska grafteoribegrepp som ger en gedigen grund för att fråga diagramdata. Genom att förstå de här grunderna kan du skriva effektivare frågor och bättre förstå hur GQL bearbetar dina data. GQL innehåller också en omfattande uppsättning funktioner och operatorer för att arbeta med grafmönster, noder, kanter och egenskaper.

Grundläggande begrepp

Det här avsnittet beskriver de grundläggande begreppen som utgör grunden för grafdataanalys med GQL.

Diagrammönster

Diagrammönster är de viktigaste byggstenarna i GQL-frågor. De beskriver den struktur som du vill hitta i dina grafdata med hjälp av en deklarativ syntax som speglar den visuella representationen av grafer.

Nodmönster

Nodmönster anger hur du matchar enskilda noder i diagrammet:

(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

Viktiga begrepp:

  • Variabelbindning: (n) skapar en variabel n som du kan referera till senare i frågan

  • Anonyma noder: (:Person) matchar noder utan att skapa en variabel

  • Etikettfiltrering: :Person begränsar matchningar till noder med etiketten Person

  • Etikettkombinationer: Använd & för AND, | för OR-åtgärder

Kantmönster

Gränsmönster definierar hur noder ansluter till varandra:

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

Viktiga begrepp:

  • Riktning: -> för utgående, <- inkommande, - för valfri riktning

  • Kanttyper: Använd etiketter som :works_at för att filtrera efter relationstyp

  • Flera typer: knows|likes matchar någon av relationstyperna

Etikettuttryck

Etiketter ger semantisk betydelse för noder och kanter. GQL stöder komplexa etikettuttryck:

:Person&amp;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 måste ha alla angivna etiketter

  • | (ELLER): Noden måste ha minst en angiven etikett

  • ! (INTE): Noden får inte ha den angivna etiketten

  • () : Parenteser för gruppering av komplexa uttryck

Sökvägsmönster

Sökvägsmönster beskriver relationer med flera hopp 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

Sökvägar med variabel längd:

  • {2,4}: Exakt 2 till 4 hopp

  • {1,}: 1 eller fler hopp (obundna). Obundna sökvägsfrågor är begränsade till 8 hopp.

  • {,5}: Upp till 5 hopp

  • {5}: Exakt 5 hopp

Sökvägsvariabler

  • p=()->(): Samlar in hela sökvägen för senare analys

  • Åtkomst med NODES(p), RELATIONSHIPS(p), PATH_LENGTH(p)

Flera mönster

GQL stöder komplexa, icke-linjära grafstrukturer:

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

Mönstersammansättning:

  • Använda kommatecken , för att avgränsa flera mönster
  • Alla mönster måste matcha samtidigt
  • Variabler kan delas mellan mönster

Matchningslägen

GQL stöder olika sökvägsmatchningslägen som styr hur mönster matchas mot grafdata. Dessa lägen påverkar prestanda, resultat fullständighet och de typer av sökvägar som returneras.

Matchningslägen styr hur grafelement kan återanvändas mellan mönstervariabler i en enda MATCH-sats.

OLIKA KANTER (standard)

Standardläget. En matchad kant kan inte bindas till fler än en kantvariabel, men noder kan återanvändas fritt.

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

REPETERBARA ELEMENT

Gör att både kanter och noder kan återanvändas mellan mönstervariabler utan begränsningar.

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

Sökvägslägen

Sökvägslägen styr vilka typer av sökvägar som ingår i resultat baserat på upprepningsbegränsningar.

TRAIL

Filtrerar bort sökvägar som har upprepande kanter. Noder kan upprepas, men varje kant kan bara visas en gång per sökväg.

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

Referens för funktioner och operatorer

Graph Query Language (GQL) innehåller en omfattande uppsättning funktioner och operatorer som fungerar med grafmönster, noder, kanter och egenskaper.

Kärnfunktioner och operatorer för GQL

I följande tabell visas kärnfunktioner och operatorer för GQL samt exempel.

GQL-funktion/operator Beskrivning GQL-exempel
MATCH Hitta diagrammönster MATCH (a)-[r]->(b)
VALFRI MATCHNING Hitta mönster som kanske inte finns VALFRI MATCHNING (p)->(c:City)
DÄR Filtermönster och egenskaper WHERE person.age > 25
FILTER Motsvarar WHERE men används utan MATCH-satser FILTER p.name = 'Carol' OR c.name = 'Seattle'
ÄR NULL Sök efter null-värden DÄR person.age ÄR NULL
ÄR INTE NULL Sök efter värden som inte är null DÄR person.age INTE ÄR NULL
ÅTERVÄNDA Projektresultat RETURN person.name, person.age
DISTINKTA Returnera unika värden RETURNERA DISTINKTA person.name
COUNT(*) Räkna alla rader RETURANTAL(*)
COUNT() Räkna värden som inte är null ANTAL RETURN(person.name)
SUM() Summera numeriska värden RETURN SUM(person.age)
MIN() Minsta värde RETURN MIN(person.age)
MAX() Maximalt värde RETURN MAX(person.age)
AVG() Genomsnittligt värde RETURN AVG(person.age)
COLLECT_LIST() Samla in värden i matrisen RETURN COLLECT_LIST(person.name)
SIZE() Matrislängd RETURSTORLEK(COLLECT_LIST(n.firstName))
labels() Visa etiketter för en nod eller kant RETURetiketter(entitet)
UPPER() Konvertera till versaler RETURNERA UPPER(person.name)
LOWER() Konvertera till gemener RETURN LOWER(person.name)
BÖRJAR MED Strängen börjar med mönster DÄR person.name BÖRJAR MED "Tom"
SLUTAR MED Strängen slutar med mönster DÄR person.name SLUTAR MED "Hanks"
INNEHÅLLER Strängen innehåller mönster DÄR person.name INNEHÅLLER "Tom"
|| Sammanfogning av strängar RETURN n.firstName || ' ' || n.lastName
TRIM() Ta bort tomt utrymme från båda ändar RETURN TRIM(' abc ')
STRING_JOIN() Koppla matriselement med avgränsare RETURN STRING_JOIN(["a", "b" || "c"], "-")
CAST() Konvertera datatyper CAST(person.age AS STRING)
ZONED_DATETIME() Skapa datetime från sträng ZONED_DATETIME('2024-01-01')
PATH_LENGTH() Hämta längden på en sökväg RETURN PATH_LENGTH(path_variable)
ORDER BY Sortera resultat ORDER BY person.age DESC
GRÄNS Begränsa antalet resultat GRÄNS 10
& (AND) Skärningspunkt för etikett MATCH (p:Person & Man)
| (ELLER) Etikettunion MATCH (n:Person | Film)
! (INTE) Etikett negation MATCH (p:! Kvinna)

Metodtips

  • GQL definierar inte tydligt hur dynamiska typer ska hanteras. Undvik körningsfel genom att uttryckligen omvandla kapslade fält till deras förväntade typ (se CAST).

Prestandaoptimering

Använd dessa strategier för att optimera GQL-frågeprestanda i produktionsmiljöer:

Tips

Börja med enkla mönster och öka sedan komplexiteten om det behövs. Övervaka frågeprestanda och justera sökvägslängder och filter för att förbättra resultatet.

Begränsa sökvägsmatchningsomfång:

  • Använd specifika etikettfilter för att minska sökutrymmet: MATCH (start:SpecificType) i stället för MATCH (start)

  • Begränsa sökvägar för variabellängd med rimliga gränser: MATCH (a)-[]->{1,3}(b) i stället för obundna sökvägar

  • Använd WHERE-satser tidigt för att filtrera resultat före dyra åtgärder.

Använd COUNT(*) för existenskontroller:

Om du bara behöver kontrollera om det finns ett mönster använder du COUNT(*) i stället för att returnera fullständiga resultat.

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

Begränsningar

  • Frågestruktur: Alla GQL-frågor måste börja med en MATCH-instruktion.

  • Reserverade nyckelord: Vissa GQL-nyckelord kan inte användas som identifierare i frågor. Vissa reserverade nyckelord är inte omedelbart uppenbara (till exempel är DATE ett reserverat nyckelord). Om dina grafdata har egenskapsnamn som står i konflikt med reserverade GQL-nyckelord använder du olika egenskapsnamn i grafschemat eller byter namn på dem för att undvika parsningskonflikter.

Viktigt

När du utformar grafschemat kan vissa vanliga egenskapsnamn vara i konflikt med reserverade GQL-nyckelord. Undvik eller byt namn på dessa egenskapsnamn.

  • Inget STÖD för INSERT/CREATE: Åtgärder för att ändra diagramstrukturer stöds inte.

  • Valfria matchningar: Stöds endast för nodmönster (inte kanter).

  • Entitetsmotsvarighetskontroller stöds inte: GQL (MATCH (n)-[]-(n2) WHERE n1 <> n2) stöds inte. Använd explicita fältjämförelser i stället, till exempel n.id <> n2.id

  • Tid och tidszon: Motorn körs i UTC. Datetime-literaler måste använda zondelad datetime. endast UTC-zonen stöds via ZONED_DATETIME("2011-12-31 23:59:59.9").

  • Varaktighetskornighet: Varaktigheter stöder upp till dagar och mindre enheter ned till nanosekunder. Enheter som är större än dagen (till exempel veckor, månader och år) stöds inte.

Anpassad GQL-funktion för Labels()

Funktionen labels() visar etiketterna för en nod eller kant som en matris.

Syntax:

labels(entity)

Parametrar:entity: En nod eller kantvariabel från ett matchat mönster.

Returnerar:

Returnerar en matris med strängar med alla etiketter för den angivna entiteten.

Exempel:

Visa etiketter för matchade noder:

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

Utdata

Den här frågan visar namnet och alla etiketter för varje nod i diagrammet.

entity.name labels(entity)
john.doe ["Användare"]
admin.user ["Användare"]
webbserver ["System"]
Databas ["System"]
domänkontrollant ["System"]

Visa etiketter i projektioner med alias:

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

Den här frågan visar nodnamn, deras etiketter och etiketterna för att ansluta kanter.

n.name n_labels edge_labels target.name
john.doe ["Användare"] ["CAN_ACCESS"] webbserver
admin.user ["Användare"] ["CAN_ACCESS"] domänkontrollant
webbserver ["System"] ["CAN_ACCESS"] Databas
domänkontrollant ["System"] ["CAN_ACCESS"] Databas
  • Last updated on