Informazioni di riferimento su Graph Query Language (GQL) (anteprima)

Cambiare i servizi usando l'elenco a discesa Version .Switch services using the Version drop-down list. Altre informazioni sulla navigazione.
Si applica a: ✅ Esplora dati di Azure in Microsoft Fabric ✅

Introduzione

Questo riferimento illustra i concetti fondamentali, le funzioni e gli operatori di Graph Query Language (GQL). Graph Query Language (GQL) è basato sui concetti matematici della teoria del grafo 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 per lavorare con modelli, nodi, bordi e proprietà del grafo.

Concetti fondamentali

Questa sezione illustra i concetti di base che costituiscono la base dell'analisi dei dati del grafo con GQL.

Modelli di grafo

I modelli di grafo 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 trovare le corrispondenze con 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 in un secondo momento nella query
• Nodi anonimi: (:Person) corrisponde ai nodi senza creare una variabile
• Filtro delle etichette: :Person limita le corrispondenze ai nodi con l'etichetta Person
• Combinazioni di etichette: usare & per AND, | per le operazioni OR

Modelli di arco

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 in uscita, <- per in ingresso, - per qualsiasi direzione
• Tipi di arco: usare etichette come :works_at filtrare in base al tipo di relazione
• Più tipi: knows|likes corrisponde a uno dei due tipi di relazione

Espressioni di etichetta

Le etichette forniscono un significato semantico ai nodi e ai bordi. 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 or more 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 vincoli)
• {,3}: fino a 3 hop
• {5}: esattamente 5 hop

Variabili di percorso:

• p=()->(): acquisisce l'intero percorso per un'analisi successiva
• Accesso con NODES(p), RELATIONSHIPS(p), PATH_LENGTH(p)

Più modelli

GQL supporta strutture di gragrafi complesse e non lineari:

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

Composizione modello:

• Usare le virgole , per separare più modelli
• Tutti i modelli devono corrispondere simultaneamente
• 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 grafo possono essere riutilizzati tra le variabili del modello all'interno di una singola clausola MATCH.

DIFFERENT EDGE (impostazione predefinita)

Modalità predefinita in Kusto. Un bordo corrispondente non può essere associato a più di una variabile perimetrale, 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 i bordi che i nodi tra le variabili del 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.

WALK (impostazione predefinita)

Modalità percorso GQL predefinita. Include tutti i percorsi possibili senza restrizioni per la ripetizione dei nodi o dei bordi.

MATCH WALK (a)-[]->{1,3}(b)
-- Allows paths with repeating nodes and edges

SENTIERO

Filtra i percorsi con bordi ripetuti. I nodi possono essere ripetuti, ma ogni arco 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

ACICLICO

Filtra i percorsi con nodi ripetuti. Ogni nodo può essere visualizzato una sola volta per percorso.

MATCH ACYCLIC (a)-[]->{1,3}(b)
-- No node can appear twice in the same path
-- Prevents cycles entirely

SEMPLICE

Uguale a ACYCLIC, ma consente ai primi e agli ultimi nodi nel percorso di essere uguali (formando un ciclo semplice).

MATCH SIMPLE (a)-[]->{1,3}(b)
-- No node repetition except first/last can match
-- Currently not supported in implementation

Combinazioni di modalità e parametro cicli Kusto

Diverse combinazioni di modalità di corrispondenza e modalità percorso vengono mappate a valori di parametro Kusto cycles specifici:

MODALITÀ ARCHI DIVERSI

MODALITÀ ELEMENTI RIPETIBILI

Esempi di sintassi

Modalità di percorso di base

-- Default (WALK with DIFFERENT EDGES)
MATCH (n)-[]->(m)
RETURN n, m

-- Explicit WALK mode
MATCH WALK (n)-[]->(m)
RETURN n, m

-- TRAIL mode - no repeating edges
MATCH TRAIL (n)-[]->{1,3}(m)
RETURN n, m

-- ACYCLIC mode - no repeating nodes
MATCH ACYCLIC (n)-[]->{1,3}(m)
RETURN n, m

Combinazioni di modalità di corrispondenza

-- DIFFERENT EDGES with WALK (default)
MATCH DIFFERENT EDGES WALK (n)-[]->(m)
RETURN n, m

-- REPEATABLE ELEMENTS with WALK
MATCH REPEATABLE ELEMENTS WALK (n)-[]->(m)
RETURN n, m

-- REPEATABLE ELEMENTS with TRAIL
MATCH REPEATABLE ELEMENTS TRAIL (n)-[]->(m)
RETURN n, m

Query a più criteri

-- Multiple WALK patterns (star pattern)
MATCH WALK (n)-[]->(a), WALK (n)-[]->(b)
RETURN n, a, b

-- Mixed path modes (both must be WALK/TRAIL for multi-path)
MATCH WALK (n)-[]->(a), TRAIL (n)-[]->(b)
RETURN n, a, b

Informazioni di riferimento su funzioni e operatori

Graph Query Language (GQL) offre un set completo di funzioni e operatori per lavorare con modelli, nodi, archi e proprietà del grafo.

Funzioni e operatori GQL principali

Questa tabella elenca le funzioni e gli operatori GQL principali, insieme agli esempi e agli equivalenti KQL (Kusto Query Language).

Procedure consigliate

• KQL supporta i tipi dinamici, ma GQL non definisce chiaramente come devono essere gestiti. Per evitare errori di runtime, eseguire il cast esplicito dei campi annidati nel tipo previsto (vedere CAST).

• Poiché GQL viene eseguito in KQL, alcune operazioni ereditano la semantica KQL. Ad esempio, COLLECT_LIST (l'equivalente GQL di make_list) appiattirà le matrici se il campo è già una matrice. Se i risultati differiscono dalle aspettative, consultare la documentazione di KQL per la funzione equivalente.

Ottimizzazione delle prestazioni

Usare queste strategie per ottimizzare le prestazioni delle query GQL negli ambienti di produzione:

Limitare l'ambito di corrispondenza del percorso:

• Usare filtri di etichetta specifici per ridurre lo spazio di ricerca: MATCH (start:SpecificType) invece di MATCH (start)
• Limitare i percorsi di lunghezza variabile con limiti ragionevoli: MATCH (a)-[]->{1,3}(b) invece di percorsi non associati
• Applicare WHERE le clausole in anticipo per filtrare i risultati prima delle operazioni costose.

Usare COUNT(*) per i controlli di esistenza:

Se è sufficiente verificare se esiste un modello, usare COUNT(*) anziché restituire i risultati completi.

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

Limitazioni

• Struttura di query: tutte le query openCypher 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 grafo hanno nomi di proprietà in conflitto con 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 grafo, alcuni nomi di proprietà comuni potrebbero essere in conflitto con parole chiave riservate GQL. Evitare o rinominare questi nomi di proprietà.

• No INSERT/CREATE supporto: le operazioni per modificare le strutture del grafo non sono supportate. Usare invece KQL per tutte le attività di creazione, modifica e gestione dei grafi.

• Corrispondenze facoltative: supportate solo per i modelli di nodo (non per i bordi).

• Controlli di equivalenza delle(MATCH (n)-[]-(n2) WHERE n1 <> n2) entità non supportati: GQL non è supportato. Usare invece confronti di campi espliciti, n.id <> n2.idad esempio .

• Fuso orario e fuso orario: il motore funziona in formato UTC. I valori letterali datetime devono usare datetime con zone; 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.

• Modalità di attraversamento: GQL definisce le modalità di attraversamento configurabili per la corrispondenza e i percorsi. Per MATCH, le modalità sono 'DIFFERENT EDGES' e 'REPEATABLE EDGES'; per PATH, le modalità sono 'WALK', 'TRAIL''ACYCLIC', e 'SIMPLE'. Per impostazione predefinita, l'implementazione corrente è 'DIFFERENT EDGES' rispettivamente e 'WALK'. Alcune combinazioni non sono supportate.

Label() funzione GQL personalizzata

La labels() funzione mostra le etichette per un nodo o un bordo come matrice.

Sintassi:

labels( entità')

Parametri:

• entity: variabile nodo o arco da un criterio 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)

Risultato

Questa query mostra il nome e tutte le etichette per ogni nodo nel grafico.

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.

Contenuti correlati

• Panoramica di Graph Query Language (GQL)
• Modelli di query GQL, esempi e casi d'uso
• Panoramica degli operatori graph
• Operatore make-graph
• Operatore graph-match
• Esercitazione: Creare il primo grafo
• Informazioni di riferimento sulle funzioni graph