Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Si applica a: Microsoft Sentinel Graph
Nota
Il supporto GQL è disponibile in anteprima. Le funzionalità e la sintassi possono cambiare in base al feedback e allo sviluppo in corso.
Questo riferimento illustra i concetti, le funzioni e gli operatori fondamentali di Graph Query Language (GQL). Graph Query Language (GQL) si basa su concetti di teoria dei grafi matematici che forniscono una solida base per l'esecuzione di query sui dati del grafo. Comprendere questi concetti fondamentali consente di scrivere query più efficaci e comprendere meglio il modo in cui GQL elabora i dati. GQL offre anche un set completo di funzioni e operatori da usare con modelli di grafi, nodi, archi e proprietà.
Concetti fondamentali
Questa sezione illustra i concetti fondamentali che costituiscono la base dell'analisi dei dati del grafo con GQL.
Modelli di grafi
I modelli di grafico sono i blocchi predefiniti principali delle query GQL. Descrivono la struttura che si vuole trovare nei dati del grafo usando una sintassi dichiarativa che rispecchia la rappresentazione visiva dei grafici.
Modelli di nodo
I modelli di nodo specificano come associare i singoli nodi nel grafico:
(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
Concetti chiave:
Associazione di variabili:
(n)crea una variabile n a cui è possibile fare riferimento più avanti nella queryNodi anonimi:
(:Person)corrisponde ai nodi senza creare una variabileFiltro delle etichette:
:Personlimita le corrispondenze ai nodi con l'etichetta PersonCombinazioni di etichette: usare
&per AND,|per le operazioni OR
Modelli perimetrali
I modelli perimetrali definiscono il modo in cui i nodi si connettono tra loro:
-[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)
Concetti chiave:
Direzione:
->per l'uscita,<-per l'ingresso,-per qualsiasi direzioneTipi di server perimetrali: usare etichette come
:works_atper filtrare in base al tipo di relazionePiù tipi:
knows|likescorrisponde a entrambi i tipi di relazione
Espressioni di etichetta
Le etichette forniscono significato semantico a nodi e archi. GQL supporta espressioni di etichetta complesse:
:Person&Company -- Both Person AND Company labels
:Person|Company -- Person OR Company labels
:!Company -- NOT Company label
:(Person|!Company)&City -- Complex expressions with parentheses
Operatori
&(AND): Il nodo deve avere tutte le etichette specificate|(OR): Il nodo deve avere almeno un'etichetta specificata!(NOT): il nodo non deve avere l'etichetta specificata(): parentesi per il raggruppamento di espressioni complesse
Modelli di percorso
I modelli di percorso descrivono le relazioni multi hop nel grafico:
(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
Percorsi a lunghezza variabile:
{2,4}: esattamente da 2 a 4 hop{1,}: 1 o più hop (senza limiti). Le query di percorso non associato sono limitate a 8 hop.{,5}: fino a 5 hop{5}: esattamente 5 hop
Variabili di percorso
p=()->(): acquisisce l'intero percorso per un'analisi successivaAccedere con
NODES(p), ,RELATIONSHIPS(p)PATH_LENGTH(p)
Più modelli
GQL supporta strutture a grafi complesse e non lineari:
(a)->(b), (a)->(c) -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d) -- Non-linear structures
Composizione del modello:
- Usare le virgole
,per separare più modelli - Tutti i modelli devono corrispondere contemporaneamente
- Le variabili possono essere condivise tra modelli
Modalità di corrispondenza
GQL supporta diverse modalità di corrispondenza dei percorsi che controllano il modo in cui i modelli vengono confrontati con i dati del grafo. Queste modalità influiscono sulle prestazioni, sulla completezza dei risultati e sui tipi di percorsi restituiti.
Le modalità di corrispondenza controllano il modo in cui gli elementi del grafico possono essere riutilizzati tra variabili di pattern all'interno di una singola clausola MATCH.
DIFFERENT EDGES (impostazione predefinita)
Modalità predefinita. Un bordo corrispondente non può essere associato a più variabili perimetrali, ma i nodi possono essere riutilizzati liberamente.
MATCH (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 must be different edges
-- a, b, c can be the same or different nodes
ELEMENTI RIPETIBILI
Consente di riutilizzare sia gli archi che i nodi tra variabili di modello senza restrizioni.
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
Modalità percorso
Le modalità percorso controllano i tipi di percorsi inclusi nei risultati in base ai vincoli di ripetizione.
SENTIERO
Filtra i percorsi con bordi ripetuti. I nodi possono essere ripetuti, ma ogni bordo può essere visualizzato una sola volta per percorso.
MATCH TRAIL (a)-[]->{1,3}(b)
-- No edge can appear twice in the same path
-- Nodes may repeat
Informazioni di riferimento su funzioni e operatori
Graph Query Language (GQL) offre un set completo di funzioni e operatori da usare con modelli di grafi, nodi, archi e proprietà.
Funzioni e operatori GQL di base
La tabella seguente elenca le funzioni e gli operatori GQL di base e gli esempi.
| Funzione/operatore GQL | Descrizione | Esempio GQL |
|---|---|---|
| CONFRONTA | Trovare i modelli di grafo | MATCH (a)-[r]->(b) |
| CORRISPONDENZA FACOLTATIVA | Trovare modelli che potrebbero non esistere | CORRISPONDENZA FACOLTATIVA (p)->(c:City) |
| DOVE | Filtrare modelli e proprietà | WHERE person.age > 25 |
| FILTRO | Equivalente a WHERE ma usato senza clausole MATCH | FILTER p.name = 'Carol' OR c.name = 'Seattle' |
| IS NULL | Verificare la presenza di valori Null | WHERE person.age IS NULL |
| NON È NULL | Verificare la presenza di valori non Null | WHERE person.age NON È NULL |
| RITORNO | Risultati del progetto | RETURN person.name, person.age |
| DISTINTI | Restituisce valori univoci | PERSON.NAME RETURN DISTINCT |
| COUNT(*) | Contare tutte le righe | RETURN COUNT(*) |
| COUNT() | Conteggio dei valori non Null | RETURN COUNT(person.name) |
| SUM() | Sommare i valori numerici | RETURN SUM(person.age) |
| MIN() | Valore minimo | RETURN MIN(person.age) |
| MAX() | Valore massimo | RETURN MAX(person.age) |
| AVG() | Valore medio | RETURN AVG(person.age) |
| COLLECT_LIST() | Raccogliere i valori nella matrice | RETURN COLLECT_LIST(person.name) |
| SIZE() | Lunghezza matrice | RETURN SIZE(COLLECT_LIST(n.firstName)) |
| labels() | Visualizzare le etichette per un nodo o un bordo | ETICHETTE RETURN(entità) |
| UPPER() | Converti in maiuscolo | RETURN UPPER(person.name) |
| LOWER() | Converti in minuscolo | RETURN LOWER(person.name) |
| INIZIA CON | La stringa inizia con il modello | DOVE person.name INIZIA CON 'Tom' |
| TERMINA CON | La stringa termina con il criterio | WHERE person.name TERMINA CON 'Hanks' |
| CONTIENE | La stringa contiene il modello | WHERE person.name CONTAINS 'Tom' |
| || | Concatenamento di stringhe | RETURN n.firstName || ' ' || n.lastName |
| TRIM() | Rimuovere gli spazi vuoti da entrambe le estremità | RETURN TRIM(' abc ') |
| STRING_JOIN() | Unire elementi della matrice con delimitatore | RETURN STRING_JOIN(["a", "b" || "c"], "-") |
| CAST() | Convertire i tipi di dati | CAST(person.age AS STRING) |
| ZONED_DATETIME() | Creare datetime dalla stringa | ZONED_DATETIME('2024-01-01') |
| PATH_LENGTH() | Ottenere la lunghezza di un percorso | RETURN PATH_LENGTH(path_variable) |
| ORDER BY | Ordina risultati | ORDER BY person.age DESC |
| LIMITE | Limitare il numero di risultati | LIMITE 10 |
| & (AND) | Intersezione delle etichette | MATCH (p:Person & Male) |
| | (OR) | Unione di etichette | MATCH (n:Person | Film) |
| ! (NOT) | Negazione di etichette | MATCH (p:! Femmina) |
Procedure consigliate
- GQL non definisce chiaramente come devono essere gestiti i tipi dinamici. Per evitare errori di runtime, eseguire il cast esplicito dei campi annidati al tipo previsto (vedere CAST).
Ottimizzazione delle prestazioni
Usare queste strategie per ottimizzare le prestazioni delle query GQL negli ambienti di produzione:
Consiglio
Iniziare con modelli semplici, quindi aumentare la complessità, se necessario. Monitorare le prestazioni delle query e modificare le lunghezze dei percorsi e i filtri per migliorare i risultati.
Limitare l'ambito di corrispondenza dei percorsi:
Usare filtri di etichetta specifici per ridurre lo spazio di ricerca: MATCH (start:SpecificType) anziché MATCH (start)
Limitare i percorsi di lunghezza variabile con limiti ragionevoli: MATCH (a)-[]->{1,3}(b) anziché percorsi non associati
Applicare le clausole WHERE in anticipo per filtrare i risultati prima di operazioni costose.
Usare COUNT(*) per i controlli dell'esistenza:
Se è necessario controllare solo se esiste un criterio, usare COUNT(*) invece di restituire risultati completi.
MATCH (user:User)-[:SUSPICIOUS_ACTIVITY]->(target)
WHERE user.id = 'user123'
RETURN COUNT(*) > 0 AS HasSuspiciousActivity
Limitazioni
Struttura di query: tutte le query GQL devono iniziare con un'istruzione MATCH.
Parole chiave riservate: alcune parole chiave GQL non possono essere usate come identificatori nelle query. Alcune parole chiave riservate non sono immediatamente ovvie,ad esempio DATE è una parola chiave riservata. Se i dati del grafico hanno nomi di proprietà in conflitto con le parole chiave riservate GQL, usare nomi di proprietà diversi nello schema del grafo o rinominarli per evitare conflitti di analisi.
Importante
Quando si progetta lo schema del grafico, alcuni nomi di proprietà comuni potrebbero essere in conflitto con le parole chiave riservate GQL. Evitare o rinominare questi nomi di proprietà.
Nessun supporto INSERT/CREATE: le operazioni per modificare le strutture del grafico non sono supportate.
Corrispondenze facoltative: supportate solo per i modelli di nodo (non i bordi).
Controlli di
(MATCH (n)-[]-(n2) WHERE n1 <> n2)equivalenza delle entità non supportati: GQL non è supportato. Usare invece confronti espliciti dei campi, ad esempion.id <> n2.idOra e fuso orario: il motore funziona in formato UTC. I valori letterali datetime devono usare datetime zoned; solo la zona UTC è supportata tramite
ZONED_DATETIME("2011-12-31 23:59:59.9").Granularità della durata: le durate supportano fino a giorni e unità più piccole fino a nanosecondi. Le unità più grandi del giorno (ad esempio, settimane, mesi, anni) non sono supportate.
Funzione GQL personalizzata Labels()
La labels() funzione mostra le etichette per un nodo o un bordo come matrice.
Sintassi:
labels(entity)
Parameters:entity: un nodo o una variabile perimetrale da un modello corrispondente.
Restituisce:
Restituisce una matrice di stringhe con tutte le etichette per l'entità specificata.
Esempi:
Mostra etichette per i nodi corrispondenti:
MATCH (entity)
RETURN entity.name, labels(entity)
Output
Questa query mostra il nome e tutte le etichette per ogni nodo nel grafico.
| entity.name | labels(entity) |
|---|---|
| john.doe | ["Utente"] |
| admin.user | ["Utente"] |
| server Web | ["System"] |
| Database | ["System"] |
| domain-controller | ["System"] |
Mostra etichette nelle proiezioni con alias:
MATCH (n)-[e]->(target)
RETURN n.name, labels(n) AS n_labels, labels(e) AS edge_labels, target.name
Questa query mostra i nomi dei nodi, le relative etichette e le etichette dei bordi di connessione.
| n.name | n_labels | edge_labels | target.name |
|---|---|---|---|
| john.doe | ["Utente"] | ["CAN_ACCESS"] | server Web |
| admin.user | ["Utente"] | ["CAN_ACCESS"] | domain-controller |
| server Web | ["System"] | ["CAN_ACCESS"] | Database |
| domain-controller | ["System"] | ["CAN_ACCESS"] | Database |