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.
Annotazioni
Questa funzionalità è attualmente disponibile in anteprima pubblica. Questa anteprima viene messa a disposizione senza contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.
GQL Graph Query Language è il linguaggio di query standardizzato ISO per i database a grafo. Consente di eseguire query e lavorare con i dati del grafo in modo efficiente.
GQL è sviluppato dallo stesso gruppo di lavoro ISO che standardizza SQL, garantendo coerenza e rigore. Se conosci SQL, troverai molte somiglianze in GQL (espressioni, predicati, tipi) - il che rende più facile iniziare. Questa guida serve sia i nuovi arrivati a imparare i concetti fondamentali di GQL che gli utenti esperti che cercano tecniche avanzate e informazioni di riferimento complete.
Annotazioni
Lo standard internazionale ufficiale per GQL è ISO/IEC 39075 Information Technology - Linguaggi di database - GQL.
Prerequisiti
Prima di approfondire GQL, è necessario avere familiarità con questi concetti:
- Comprensione di base dei database - L'esperienza con qualsiasi sistema di database (come relazionale (SQL), NoSQL o grafico) è utile
- Concetti relativi ai gragrafi - Informazioni su nodi, archi e relazioni nei dati connessi
- Nozioni fondamentali sulle query : conoscenza dei concetti di base delle query, ad esempio il filtro, l'ordinamento e l'aggregazione
Sfondo consigliato:
- L'esperienza con i linguaggi SQL o openCypher rende più facile imparare la sintassi GQL (sono le radici di GQL)
- Familiarità con la modellazione dei dati consente di progettare schemi a grafo
- Informazioni sul caso d'uso specifico per i dati del grafo
Elementi necessari:
- Accesso a Microsoft Fabric con funzionalità a grafo
- Dati di esempio o disponibilità a lavorare con i nostri esempi di social network
- Editor di testo di base per la scrittura di query
Suggerimento
Se non si ha familiarità con i database a grafo, iniziare con la panoramica dei modelli di dati del grafo prima di continuare con questa guida.
Cosa rende GQL speciale
GQL è progettato specificamente per i dati del grafo. In questo modo è naturale e intuitivo lavorare con le informazioni connesse.
A differenza di SQL, che si basa su table joins per esprimere relazioni, GQL utilizza pattern grafici visivi, che riflettono direttamente come le entità sono connesse, rendendo le query più facili da leggere e da ragionare.
Supponiamo che tu voglia trovare persone e i loro amici (persone che si conoscono) che siano nati prima del 1999. Ecco come GQL lo esprime usando un pattern grafico visivo:
MATCH (person:Person)-[:knows]-(friend:Person)
WHERE person.birthday < 19990101
AND friend.birthday < 19990101
RETURN person.firstName || ' ' || person.lastName AS person_name,
friend.firstName || ' ' || friend.lastName AS friend_name
Questa query trova amici (persone che si conoscono tra loro) che sono entrambi nati prima del 1999. Il modello (person:Person)-[:knows]-(friend:Person) mostra visivamente la struttura di relazione che si sta cercando, in modo analogo al disegno di un diagramma dei dati.
Nozioni fondamentali su GQL
Prima di approfondire le query, comprendere questi concetti di base che costituiscono la base di GQL:
- I grafi memorizzano i tuoi dati come nodi (entità) e archi (relazioni), ciascuno con etichette e proprietà
- I tipi di grafo agiscono come schemi, definendo quali nodi e archi possono esistere nel grafico
- I vincoli sono regole aggiuntive e restrizioni imposte dai tipi di grafo sui grafi per garantire l'integrità dei dati
-
Le query usano istruzioni come
MATCH,FILTEReRETURNper elaborare i dati e visualizzare i risultati - I modelli descrivono le strutture del grafo che si desidera trovare usando la sintassi visiva intuitiva
- Le espressioni eseguono calcoli e confronti sui dati, in modo simile alle espressioni SQL
- I predicati sono espressioni di valore booleane usate per filtrare i risultati all'interno delle query
- I tipi valore definiscono i tipi di valori che è possibile elaborare e archiviare
Informazioni sui dati del grafo
Per lavorare in modo efficace con GQL, è necessario comprendere come sono strutturati i dati del grafo. Questa base consente di scrivere query migliori e modellare i dati in modo efficace.
Nodi e archi: blocchi predefiniti
In GQL si lavora con grafici delle proprietà etichettati. Un grafico è costituito da due tipi di elementi:
I nodi rappresentano in genere le entità (i "sostantivi") nel sistema, ad esempio persone, organizzazioni, post o prodotti. Sono oggetti indipendenti presenti nel dominio. I nodi sono talvolta detti anche vertici.
Gli archi rappresentano le relazioni tra entità (verbi), ovvero il modo in cui le entità si connettono e interagiscono.
Ad esempio, le persone si conoscono (:knows), organizzazioni che operano in specifiche regioni (:operates), o clienti che hanno acquistato prodotti (:purchased).
I bordi sono talvolta detti anche relazioni.
Ogni elemento del grafo presenta queste caratteristiche:
- ID interno che lo identifica in modo univoco
-
Una o più etichette: nomi descrittivi come
Personoknows. In Microsoft Fabric, gli archi dei grafi hanno sempre esattamente un'etichetta. -
Proprietà—coppie nome-valore che memorizzano dati sull'elemento (come
firstName: "Alice"obirthday: "19730108").
Struttura dei grafici
Ogni arco si connette esattamente a due nodi: un'origine e una destinazione. Questa connessione crea la struttura del grafo e mostra come le entità sono correlate tra loro. La direzione dei bordi è importante: un Person altro follows che Person crea una relazione diretta.
Annotazioni
Attualmente Graph in Microsoft Fabric non supporta gli archi non indirizzati.
I grafi di proprietà come supportati in Microsoft Fabric sono sempre ben formati, il che significa che ogni arco collega due nodi validi. Se viene visualizzato un bordo in un grafico, entrambi i relativi endpoint sono presenti nello stesso grafico.
Modelli a grafo e tipi di grafo
La struttura di un grafico in Microsoft Fabric è descritta dal modello a grafo, che funge da schema di database per il dominio dell'applicazione. I modelli a grafo definiscono:
- Quali nodi e archi possono esistere
- Quali etichette e proprietà possono avere
- Modalità di connessione di nodi e archi
I modelli a grafo garantiscono anche l'integrità dei dati tramite vincoli, in particolare vincoli di chiave del nodo che specificano quali proprietà identificano in modo univoco ogni nodo.
Annotazioni
I modelli a grafo possono essere specificati usando la sintassi standard GQL, nel qual caso sono chiamati tipi di grafo.
Un esempio pratico: social network
In questa documentazione viene usato un esempio di social network per illustrare i concetti di GQL. La comprensione di questo dominio consente di seguire gli esempi e applicare modelli simili ai propri dati.
Annotazioni
Il social network è un esempio derivato dal LDBC SNB (LDBC Social Network Benchmark) pubblicato dal GDC (Graph Data Council). Per altri dettagli, vedere l'articolo "The LDBC Social Network Benchmark".
Entità di social network
Il social network include questi tipi principali di nodi, che rappresentano le entità del dominio:
Le persone hanno informazioni personali come nomi, compleanni e sessi. Vivono in città e formano legami sociali.
I luoghi formano una gerarchia geografica:
- Città come "New York" o "Londra"
- Paesi/aree geografiche come "Stati Uniti" o "Regno Unito"
- Continenti come "America del Nord" o "Europa"
Organizzazioni in cui le persone trascorrono tempo:
- Università in cui le persone studiano
- Aziende in cui lavorano le persone
Contenuto e discussioni:
- Forum con titoli che contengono post
- Post con contenuto, lingua e immagini facoltative
- Commenti che rispondono ai post o ad altri commenti
- Tag che classificano il contenuto e rappresentano gli interessi
Come si connette tutto
Le connessioni tra le entità rendono interessante la rete:
- Le persone si conoscono (amicizie,
:knows) - Le persone lavorano in aziende (
:workAt) o studiano in università (:studyAt) - Le persone creano post e commenti (
:hasCreator) - Le persone mettono like a post e commenti (
:likes) - Post, forum e commenti possono avere tag (
:hasTag) - Le persone hanno interesse per tag specifici (
:hasInterest) - I forum contengono post (
:containerOf) e hanno membri (:hasMember) e moderatori (:hasModerator)
I bordi del grafo rappresentano le relazioni di dominio. Questa rete avanzata crea molte opportunità per query e analisi interessanti.
Le prime query GQL
Dopo aver appreso le nozioni di base sul grafo, vedere come eseguire query sui dati del grafo usando GQL. Questi esempi vengono compilati da semplici a complessi, che illustrano come l'approccio di GQL rende le query del grafo intuitive e potenti.
Iniziare con semplicità: trovare tutte le persone
Iniziamo con la query più semplice possibile, trova i nomi (nome, cognome) di tutte le persone (:Persone persone) nel grafico.
MATCH (p:Person)
RETURN p.firstName, p.lastName
Questa query viene eseguita come segue:
-
MATCHtrova tutti i nodi etichettatiPerson -
RETURNmostra il nome e il cognome
Aggiungi filtro: trovare persone specifiche
Ora troviamo persone con caratteristiche specifiche, in questo caso tutti di nome Alice, e mostriamo i loro nomi e le loro date di nascita.
MATCH (p:Person)
FILTER p.firstName = 'Annemarie'
RETURN p.firstName, p.lastName, p.birthday
Questa query viene eseguita come segue:
-
MATCHtrova tutti i nodi (p) etichettati Persona -
FILTERnodi (p) il cui nome di battesimo è Alice -
RETURNmostra il nome, il cognome e la data di nascita
Struttura di query di base
Tutte le query GQL di base seguono un modello coerente: una sequenza di istruzioni che interagiscono per trovare, filtrare e restituire dati.
La maggior parte delle query inizia con MATCH trovare i pattern nel grafico e termina con RETURN specificare l'output.
Ecco una semplice query che trova coppie di persone che si conoscono e condividono la stessa data di nascita, poi restituisce il conteggio totale di quelle coppie di amici.
MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends
Questa query viene eseguita come segue:
-
MATCHtrova tutte le coppie diPersonnodi che si conoscono tra loro -
FILTERmantiene solo le coppie in cui entrambe le persone hanno lo stesso compleanno -
RETURNconta il numero di coppie di amici esistenti
Suggerimento
Il filtro può anche essere eseguito direttamente come parte di un criterio aggiungendo una WHERE clausola .
Ad esempio, MATCH (n:Person WHERE n.age > 23) corrisponderà Person solo ai nodi la cui age proprietà è maggiore di 23.
Annotazioni
GQL supporta commenti di linea in stile // C, commenti di linea in stile -- SQL e commenti di blocco in stile /* */ C.
Affermazioni comuni
-
MATCH: Identifica il pattern grafico da cercare—qui si definisce la struttura dei dati che ti interessano. -
LET: Assegna nuove variabili o valori calcolati basandosi su dati corrispondenti—aggiunge colonne derivate al risultato. -
FILTER: Restringe i risultati applicando condizioni—rimuove le righe che non soddisfano i criteri. -
ORDER BY: Ordina i dati filtrati—aiuta a organizzare l'output in base a uno o più campi. -
OFFSETeLIMIT: Limitare il numero di righe restituite—utile per la paginazione o per query top-k. -
RETURN: Specifica l'output finale—definisce quali dati devono essere inclusi nell'insieme di risultati ed esegue l'aggregazione.
Come interagiscono le istruzioni
Le istruzioni GQL formano una pipeline, in cui ogni istruzione elabora l'output della precedente. Questa esecuzione sequenziale rende le query facili da leggere e debugare perché l'ordine di esecuzione corrisponde a quello di lettura.
Punti chiave:
- Le istruzioni vengono eseguite in modo effettivo sequenziale.
- Ogni istruzione trasforma i dati e li trasmette al successivo.
- Questo crea un flusso di dati chiaro e prevedibile che semplifica le query complesse.
Importante
Internamente, l'esecuzione delle istruzioni può essere riordinata e le singole istruzioni possono essere eseguite in parallelo da Microsoft Fabric per massimizzare le prestazioni. Tuttavia, questo non influirà sulla correttezza dei risultati.
Esempio
La seguente query GQL trova le prime 10 persone che lavorano in aziende con "Air" nel nome, le ordina per nome completo e restituisce il nome completo insieme al nome delle loro aziende.
-- Data flows: Match → Let → Filter → Order → Limit → Return
MATCH (p:Person)-[:workAt]->(c:Company) -- Input: unit table, Output: (p, c) table
LET fullName = p.firstName || ' ' || p.lastName -- Input: (p, c) table, Output: (p, c, fullName) table
FILTER c.name CONTAINS 'Air' -- Input: (p, c, fullName) table, Output: filtered table
ORDER BY fullName -- Input: filtered table, Output: sorted table
LIMIT 10 -- Input: sorted table, Output: top 10 rows table
RETURN fullName, c.name AS companyName -- Input: top 10 rows table
-- Output: projected (fullName, companyName) result table
Questa query viene eseguita come segue:
-
MATCHtrova persone che lavorano in aziende con "Air" nel nome -
LETcrea nomi completi combinando nomi di battesimo e cognomi -
FILTERtiene solo dipendenti Contoso -
ORDER BYordina per nome completo -
LIMITPrende i primi 10 risultati -
RETURNNomi dei resi e sedi delle aziende
Le variabili connettono i dati
Le variabili (ad esempio p, ce fullName negli esempi precedenti) contengono dati tra istruzioni. Quando si riutilizza un nome di variabile, GQL garantisce automaticamente che faccia riferimento agli stessi dati, creando condizioni di join avanzate. Le variabili sono talvolta denominate anche variabili di associazione.
Le variabili possono essere classificate in modi diversi:
Per origine dell'associazione:
- Variabili di criterio: associate da modelli di grafo corrispondenti
- Variabili regolari : associate da altri costrutti di linguaggio
Tipi di variabile modello:
-
Variabili di elemento : associazione ai valori di riferimento degli elementi del grafo
- Variabili del nodo : associazione a singoli nodi
- Variabili di arco : associazione a singoli bordi
- Variabili di percorso : eseguire l'associazione ai valori di percorso che rappresentano percorsi corrispondenti
Per grado di riferimento:
- Variabili singleton : associazione a singoli valori di riferimento di elementi dai modelli
- Variabili di gruppo : associare a elenchi di valori di riferimento degli elementi da modelli a lunghezza variabile (vedere Tecniche avanzate di aggregazione)
Risultati e risultati dell'esecuzione
Quando si esegue una query, si ottiene un risultato di esecuzione costituito da:
-
Tabella dei risultati (facoltativa) con i dati dell'istruzione
RETURN. - Informazioni sullo stato che indicano se la query ha avuto esito positivo o negativo.
Tabelle dei risultati
La tabella dei risultati, se presente, è il risultato effettivo dell'esecuzione della query.
Una tabella dei risultati include informazioni sul nome e sul tipo delle relative colonne, una sequenza di nomi di colonna preferita da utilizzare per visualizzare i risultati, se la tabella è ordinata e le righe effettive stesse.
Annotazioni
In caso di errore di esecuzione, non viene inclusa alcuna tabella dei risultati nel risultato dell'esecuzione.
Informazioni sullo stato
Durante l'esecuzione della query vengono rilevate varie condizioni degne di nota, ad esempio errori o avvisi. Ogni condizione di questo tipo viene registrata da un oggetto stato nelle informazioni sullo stato del risultato dell'esecuzione.
Le informazioni sullo stato sono costituite da un oggetto di stato primario e da un elenco (possibilmente vuoto) di oggetti di stato aggiuntivi. L'oggetto di stato primario è sempre presente e indica se l'esecuzione della query ha avuto esito positivo o negativo.
Ogni oggetto stato include un codice di stato a 5 cifre (denominato GQLSTATUS) che identifica la condizione registrata e un messaggio che la descrive.
Codici di stato di esito positivo:
| GQLSTATUS | Message | When |
|---|---|---|
| 00000 | nota: completamento riuscito | Operazione riuscita con almeno una riga |
| 00001 | nota: completamento riuscito - risultato omesso | Operazione riuscita senza tabella (attualmente inutilizzata) |
| 02000 | nota: nessun dato | Operazione riuscita con zero righe |
Altri codici di stato indicano altri errori o avvisi rilevati durante l'esecuzione della query.
Importante
Nel codice dell'applicazione, fare sempre affidamento sui codici di stato per testare determinate condizioni. I codici di stato sono sicuramente stabili e il loro significato generale non cambierà in futuro. Non testare il contenuto dei messaggi, poiché il messaggio concreto riportato per un codice di stato può cambiare in futuro a seconda della query o anche tra un'esecuzione e l'altra della stessa query.
Inoltre, gli oggetti di stato possono contenere un oggetto stato della causa sottostante e un record di diagnostica con ulteriori informazioni che caratterizzano la condizione registrata.
Concetti e istruzioni essenziali
Questa sezione illustra i blocchi predefiniti di base necessari per scrivere query GQL efficaci. Ogni concetto si basa sulle competenze pratiche di scrittura delle query.
Modelli di grafo: ricerca della struttura
I modelli di grafo sono l'elemento centrale delle query GQL. Consentono di descrivere la struttura dei dati che si sta cercando usando una sintassi visiva intuitiva simile alle relazioni che si desidera trovare.
Modelli semplici:
Iniziare con i modelli di relazione di base:
-- Find direct friendships
(p:Person)-[:knows]->(f:Person)
-- Find people working at any company
(p:Person)-[:workAt]->(c:Company)
-- Find cities in any country/region
(ci:City)-[:isPartOf]->(co:Country)
Modelli con dati specifici:
-- Find who works at Microsoft specifically
(p:Person)-[:workAt]->(c:Company)
WHERE p.firstName = 'Annemarie'
-- Find friends who are both young
(p:Person)-[:knows]->(f:Person)
WHERE p.birthday > 19950101 AND f.birthday > 19950101
Espressioni di etichetta per la selezione di entità flessibili:
(:Person|Company)-[:isLocatedIn]->(p:City|Country) -- OR with |
(:Place&City) -- AND with &
(:Person&!Company) -- NOT with !
Annotazioni
I modelli di grafi con etichette multiple di elementi non sono ancora supportati (problema noto).
Le espressioni di etichetta consentono di trovare le corrispondenze tra diversi tipi di nodi in un unico modello, rendendo le query più flessibili.
Il riutilizzo delle variabili crea join potenti:
-- Find coworkers: people who work at the same company
(c:Company)<-[:workAt]-(x:Person)-[:knows]-(y:Person)-[:workAt]->(c)
Il riutilizzo della variabile garantisce che entrambe c le persone lavorino nella stessa azienda, creando un vincolo di join automatico. Questo modello è un modello chiave per esprimere le relazioni "stessa entità".
Importante
Informazioni dettagliate critiche: il riutilizzo delle variabili nei modelli crea vincoli strutturali. Questa tecnica è il modo in cui si esprimono relazioni complesse del grafo come "amici che lavorano nella stessa azienda" o "persone nella stessa città".
Filtro a livello di criterio con WHERE:
-- Filter during pattern matching (more efficient)
(p:Person WHERE p.birthday < 19940101)-[:workAt]->(c:Company WHERE c.id > 1000)
-- Filter edges during matching
(p:Person)-[w:workAt WHERE w.workFrom >= 2000]->(c:Company)
Modelli a lunghezza variabile delimitata:
(:Person)-[:knows]->{1,3}(:Person) -- Friends up to 3 degrees away
Modelli TRAIL per l'attraversamento senza ciclo:
Usare TRAIL i modelli per evitare cicli durante l'attraversamento del grafico, assicurandosi che ogni bordo venga visitato al massimo una volta:
-- Find paths without visiting the same :knows edge twice
MATCH TRAIL (src:Person)-[:knows]->{1,4}(dst:Person)
WHERE src.firstName = 'Alice' AND dst.firstName = 'Bob'
RETURN count(*) AS num_connections
-- Find acyclic paths in social networks
MATCH TRAIL (p:Person)-[e:knows]->{,3}(celebrity:Person)
RETURN
p.firstName || ' ' || p.lastName AS person_name,
celebrity.firstName || ' ' || celebrity.lastName AS celebrity_name,
count(e) AS distance
LIMIT 1000
Associazione di bordi a lunghezza variabile:
Nei modelli a lunghezza variabile le variabili perimetrali acquisisce informazioni diverse in base al contesto:
-- Edge variable 'e' binds to a single edge for each result row
MATCH (p:Person)-[e:knows]->(friend:Person)
RETURN p.firstName, e.creationDate, friend.firstName -- e refers to one specific relationship
LIMIT 1000
-- Edge variable 'e' binds to a group list of all edges in the path
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)
RETURN
p.firstName || ' ' || p.lastName AS person_name,
friend.firstName || ' ' || friend.lastName AS friend_name,
-- e is a list
size(e) AS num_edges
LIMIT 1000
Questa distinzione è fondamentale per l'uso corretto delle variabili perimetrali.
Modelli complessi con più relazioni:
MATCH (p:Person), (p)-[:workAt]->(c:Company), (p)-[:isLocatedIn]->(city:City)
RETURN p.firstName, p.lastName, c.name AS company_name, city.name AS city_name
LIMIT 1000
Questo modello trova le persone insieme al luogo di lavoro e alla residenza, mostrando come una persona si connette a più altre entità.
Istruzioni principali
GQL fornisce tipi di istruzioni specifici che interagiscono per elaborare i dati del grafo in modo dettagliato. Comprendere queste istruzioni è essenziale per creare query efficaci.
MATCH istruzione
Sintassi:
MATCH <graph pattern>, <graph pattern>, ... [ WHERE <predicate> ]
L'istruzione MATCH accetta i dati di input e trova modelli di grafo, unendo variabili di input con variabili di modello e restituisce tutte le combinazioni corrispondenti.
Variabili di input e output:
-- Input: unit table (no columns, one row)
-- Pattern variables: p, c
-- Output: table with (p, c) columns for each person-company match
MATCH (p:Person)-[:workAt]->(c:Company)
Filtro a livello di istruzione con WHERE:
-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name
Tutte le corrispondenze possono essere filtrate dopo l'uso di WHERE, evitando un'istruzione separata FILTER .
Join con variabili di input:
Quando MATCH non è la prima istruzione, unisce i dati di input con corrispondenze del criterio:
...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)
Importante
Graph in Microsoft Fabric non supporta ancora la composizione arbitraria delle istruzioni. Vedere l'articolo sulle limitazioni correnti.
Comportamenti di join chiave:
Modalità di MATCH gestione dell'unione dei dati:
- Uguaglianza delle variabili: join di variabili di input con variabili di pattern usando la corrispondenza di uguaglianza
- Inner join: le righe di input senza corrispondenze dei criteri vengono eliminate (nessun join sinistro/destro)
-
Ordine di filtro: filtri a livello
WHEREdi istruzione dopo il completamento della corrispondenza dei criteri - Connettività dei modelli: più modelli devono condividere almeno una variabile per il join corretto
- Prestazioni: le variabili condivise creano vincoli di join efficienti
Importante
Restrizione: se questa MATCH non è la prima istruzione, almeno una variabile di input deve essere unita a una variabile di pattern. Più modelli devono avere una variabile in comune.
Più modelli richiedono variabili condivise:
-- Shared variable 'p' joins the two patterns
-- Output: people with both workplace and residence data
MATCH (p:Person)-[:workAt]->(c:Company),
(p)-[:isLocatedIn]->(city:City)
LET istruzione
Sintassi:
LET <variable> = <expression>, <variable> = <expression>, ...
L'istruzione LET crea variabili calcolate e abilita la trasformazione dei dati all'interno della pipeline di query.
Creazione di variabili di base:
MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000
Calcoli complessi:
MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000
Comportamenti principali:
- Le espressioni vengono valutate per ogni riga di input
- I risultati diventano nuove colonne nella tabella di output
- Le variabili possono fare riferimento solo alle variabili esistenti dalle istruzioni precedenti
- Più assegnazioni in un'unica
LETvengono valutate in parallelo (nessun riferimento incrociato)
FILTER istruzione
Sintassi:
FILTER [ WHERE ] <predicate>
L'istruzione FILTER fornisce un controllo preciso sui dati che procedono attraverso la pipeline di query.
Filtro di base:
MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *
Condizioni logiche complesse:
MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101)
OR (p.gender = 'female' AND p.birthday < 19990101)
OR p.browserUsed = 'Edge'
RETURN *
Modelli di filtro con riconoscimento dei valori Null:
Usare questi modelli per gestire i valori Null in modo sicuro:
-
Verificare la presenza di valori: -
p.firstName IS NOT NULLha un nome -
Convalidare i dati:
p.id > 0- ID valido -
Gestire i dati mancanti:
NOT coalesce(p.locationIP, '127.0.0.1') STARTS WITH '127.0.0'- Non è stato eseguito la connessione dalla rete locale -
Combinare condizioni: usare
AND/ORcon controlli Null espliciti per la logica complessa
Attenzione
Tenere presente che le condizioni che coinvolgono valori Null restituiscono UNKNOWN, che filtra tali righe. Usare controlli espliciti IS NULL quando è necessaria una logica inclusiva null.
ORDER BY istruzione
Sintassi:
ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ...
Ordinamento a più livelli con espressioni calcolate:
MATCH (p:Person)
RETURN *
ORDER BY p.firstName DESC, -- Primary: by first name (Z-A)
p.birthday ASC, -- Secondary: by age (oldest first)
p.id DESC -- Tertiary: by ID (highest first)
Gestione dei valori Null nell'ordinamento:
ORDER BY coalesce(p.gender, 'not specified') DESC -- Treat NULL as 'not specified'
Dettagli del comportamento di ordinamento:
Informazioni sul funzionamento ORDER BY :
- Valutazione delle espressioni: le espressioni vengono valutate per ogni riga, quindi i risultati determinano l'ordine di riga
- Più chiavi di ordinamento: creare un ordinamento gerarchico (primario, secondario, terziario e così via)
-
Gestione dei valori Null:
NULLviene sempre considerato come il valore più piccolo nei confronti -
Ordine predefinito:
ASC(crescente) è predefinito,DESC(decrescente) deve essere specificato in modo esplicito - Ordinamento calcolato: è possibile ordinare in base ai valori calcolati, non solo alle proprietà archiviate
Attenzione
L'ordinamento stabilito da ORDER BY è visibile solo all'istruzione immediatamente seguente.
Di conseguenza, ORDER BY seguito da RETURN * NON produce un risultato ordinato.
Confrontare:
MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
ORDER BY r.creationDate DESC
/* intermediary result _IS_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
/* final result _IS_ _NOT_ guaranteed to be ordered here */
con:
MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
/* intermediary result _IS_ _NOT_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
ORDER BY r.creationDate DESC
/* final result _IS_ guaranteed to be ordered here */
Ciò ha conseguenze immediate per le query "Top-k": LIMIT deve sempre seguire l'istruzione che ha stabilito l'ordinamento ORDER BY previsto.
OFFSETistruzioni e LIMIT
Sintassi:
OFFSET <offset> [ LIMIT <limit> ]
| LIMIT <limit>
Modelli comuni:
-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10 -- Top 10 by ID
Importante
Per risultati di impaginazione prevedibili, usare ORDER BY sempre prima OFFSET e LIMIT per garantire un ordinamento coerente delle righe tra le query.
RETURN: proiezione dei risultati di base
Sintassi:
RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]
L'istruzione RETURN produce l'output finale della query specificando i dati visualizzati nella tabella dei risultati.
Output di base:
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name,
p.birthday,
c.name
Uso degli alias per maggiore chiarezza:
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name,
p.lastName AS last_name,
c.name AS company_name
Combinare con l'ordinamento e top-k:
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name,
p.birthday AS birth_year,
c.name AS company
ORDER BY birth_year ASC
LIMIT 10
Gestione duplicata con DISTINCT:
-- Remove duplicate combinations
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN DISTINCT p.gender, p.browserUsed, p.birthday AS birth_year
ORDER BY p.gender, p.browserUsed, birth_year
Combinare con l'aggregazione:
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count
RETURN con GROUP BY: proiezione di risultati raggruppati
Sintassi:
RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]
Usare GROUP BY per raggruppare le righe in base ai valori condivisi e alle funzioni di aggregazione di calcolo all'interno di ogni gruppo.
Raggruppamento di base con aggregazione:
MATCH (p:Person)-[:workAt]->(c:Company)
LET companyName = c.name
RETURN companyName,
count(*) AS employeeCount,
avg(p.birthday) AS avg_birth_year
GROUP BY companyName
ORDER BY employeeCount DESC
Raggruppamento a più colonne:
MATCH (p:Person)
LET gender = p.gender
LET browser = p.browserUsed
RETURN gender,
browser,
count(*) AS person_count,
avg(p.birthday) AS avg_birth_year,
min(p.creationDate) AS first_joined,
max(p.id) AS highest_id
GROUP BY gender, browser
ORDER BY avg_birth_year DESC
LIMIT 10
Annotazioni
Per tecniche di aggregazione avanzate, tra cui l'aggregazione orizzontale su modelli a lunghezza variabile, vedere Tecniche avanzate di aggregazione.
Tipi di dati: uso dei valori
GQL supporta tipi di dati avanzati per l'archiviazione e la modifica di diversi tipi di informazioni nel grafico.
Tipi di valore di base:
-
Numeri:
INT64,UINT64,DOUBLEper calcoli e misurazioni -
Testo:
STRINGper nomi, descrizioni e dati testuali -
Logica:
BOOLcon tre valori: TRUE, FALSE e UNKNOWN (per la gestione dei valori Null) -
Ora:
ZONED DATETIMEper i timestamp con informazioni sul fuso orario -
Raccolte:
LIST<T>per più valori dello stesso tipoT,PATHper risultati di attraversamento di grafi -
Elementi del grafo:
NODEeEDGEper fare riferimento ai dati del grafico
Importante
Alcuni tipi di valore non sono supportati come tipi di valore immobiliare. In particolare, tutti i valori che coinvolgono valori di riferimento di elementi di grafo non possono essere usati come valori di proprietà (come elenchi di nodi o percorsi).
Valori letterali di esempio:
42 -- Integer literal
"Hello, graph!" -- String literal
TRUE -- Boolean literal
ZONED_DATETIME('2024-01-15T10:30:00Z') -- DateTime with timezone literakl
[1, 2, 3] -- Literal list of integers
Modelli di gestione dei valori Null critici:
-- Equality predicates with NULL always returns UNKNOWN
5 = NULL -- Evaluates to UNKNOWN (not FALSE!)
NULL = NULL -- Evaluates to UNKNOWN (not TRUE!)
-- Use IS NULL predicates for explicit null testing
p.nickname IS NULL -- Evaluates to TRUE if nickname is null
p.nickname IS NOT NULL -- Evaluates to TRUE if nickname has a value
-- Use the COALESCE function for null-safe value selection
coalesce(p.nickname, p.firstName, '???') -- Evaluates to first non-null value
Implicazioni per la logica a tre valori:
-- In FILTER statements, only TRUE values pass through
FILTER p.birthday > 0 -- Removes rows where birthday is null or missing or zero
-- It's important to understand that NOT UNKNOWN = UNKNOWN
FILTER NOT (p.birthday > 0) -- Removes rows where birthday is null or missing or positive
-- Use explicit null handling for inclusive filtering
FILTER p.birthday < 19980101 OR p.birthday IS NULL -- Includes null birthdays
Attenzione
La logica a tre valori indica che NULL = NULL restituisce UNKNOWN, non TRUE. Questo comportamento influisce sul filtro e sui join.
IS NULL Usare sempre per i test Null.
Espressioni: trasformazione e analisi dei dati
Le espressioni consentono di calcolare, confrontare e trasformare i dati all'interno delle query. Sono simili alle espressioni in SQL, ma hanno funzionalità aggiuntive per la gestione dei dati del grafo.
Tipi di espressione comuni:
p.birthday < 19980101 -- Birth year comparison
p.firstName || ' ' || p.lastName -- String concatenation
count(*) -- Aggregation
p.firstName IN ['Alice', 'Bob'] -- List membership
coalesce(p.firstName, p.lastName) -- Null handling
Composizione predicato complessa:
-- Combine conditions with proper precedence
FILTER (p.birthday > 19560101 AND p.birthday < 20061231)
AND ((p.gender IN ['male', 'female']) OR (p.browserUsed IS NOT NULL))
-- Use parentheses for clarity and correctness
FILTER p.gender = 'female' AND (p.firstName STARTS WITH 'A' OR p.id > 1000)
Criteri di ricerca di stringhe:
-- Pattern matching with different operators
p.locationIP CONTAINS '192.168' -- Substring search
p.firstName STARTS WITH 'John' -- Prefix matching
p.lastName ENDS WITH 'son' -- Suffix matching
-- Case-insensitive operations
upper(p.firstName) = 'ALICE' -- Convert to uppercase for comparison
Funzioni predefinite per categoria:
GQL fornisce queste categorie di funzioni per esigenze di elaborazione dei dati diverse:
-
Funzioni di aggregazione:
count(),sum()avg(), ,min(), permax()il riepilogo dei dati -
Funzioni stringa:
char_length(),upper(),lower(),trim()per l'elaborazione del testo -
Funzioni del grafo:
nodes(),edges(),labels()per l'analisi delle strutture del grafo -
Funzioni generali:
coalesce()per la gestione dei valori Null normalmente
Precedenza dell'operatore per espressioni complesse:
- Accesso alle proprietà (
.) - Moltiplicazione/divisione (
*,/) - Addizione/Sottrazione (
+,-) - Confronto (
=,<>,<>,<=, , )>= - Negazione logica (
NOT) - Congiunzione logica (
AND) - Disgiunzione logica (
OR)
Nell'elenco sopra, un operatore con numero inferiore "si lega più strettamente" di un operatore con un numero più alto.
Esempio: NOT n.prop OR m.prop è (NOT n.prop) OR m.prop ma non 'NOT (n.prop O m.prop)
Suggerimento
Usare le parentesi per rendere esplicita la precedenza. Le espressioni complesse sono più facili da leggere ed eseguire il debug quando il raggruppamento è chiaro.
Tecniche di query avanzate
In questa sezione vengono illustrati modelli e tecniche sofisticate per la creazione di query di gragrafi complesse ed efficienti. Questi modelli vanno oltre l'utilizzo di istruzioni di base per facilitare la composizione di query analitiche avanzate.
Composizione complessa con più istruzioni
Importante
Graph in Microsoft Fabric non supporta ancora la composizione arbitraria delle istruzioni. Vedere l'articolo sulle limitazioni correnti.
Comprendere come comporre query complesse in modo efficiente è fondamentale per l'esecuzione avanzata di query sui gra gragrafi.
Progressione del modello in più passaggi:
-- Build complex analysis step by step
MATCH (company:Company)<-[:workAt]-(employee:Person)
LET companyName = company.name
MATCH (employee)-[:isLocatedIn]->(city:City)
FILTER employee.birthday < 19850101
LET cityName = city.name
RETURN companyName, cityName, avg(employee.birthday) AS avgBirthday, count(employee) AS employeeCount
GROUP BY companyName, cityName
ORDER BY avgBirthday DESC
Questa query aumenta progressivamente la complessità: trovare le aziende, i loro dipendenti, le posizioni dei dipendenti, filtrare le aziende con dipendenti nati prima del 1985, calcolare la data di nascita media e riassumere e ordinare i risultati.
Uso dell'aggregazione orizzontale:
-- Find people and their minimum distance to people working at Microsoft
MATCH TRAIL (p:Person)-[e:knows]->{,5}(:Person)-[:workAt]->(:Company { name: 'Microsoft'})
LET p_name = p.lastName || ', ' || p.firstName
RETURN p_name, min(count(e)) AS minDistance
GROUP BY p_name
ORDER BY minDistance DESC
Annotazioni
Questa query non è ancora supportata (problema noto).
Ambito variabile e controllo del flusso avanzato
Le variabili connettono i dati tra istruzioni di query e abilitano attraversamenti di gragrafi complessi. La comprensione delle regole di ambito avanzate consente di scrivere query sofisticate con più istruzioni.
Binding di variabili e modelli di ambito:
-- Variables flow forward through subsequent statements
MATCH (p:Person) -- Bind p
LET fullName = p.firstName || ' ' || p.lastName -- Bind concatenation of p.firstName and p.lastName as fullNume
FILTER fullName CONTAINS 'Smith' -- Filter for fullNames with “Smith” substring (p is still bound)
RETURN p.id, fullName -- Only return p.id and fullName (p is dropped from scope)
Riutilizzo delle variabili per i join tra istruzioni:
-- Multi-statement joins using variable reuse
MATCH (p:Person)-[:workAt]->(:Company) -- Find people with jobs
MATCH (p)-[:isLocatedIn]->(:City) -- Same p: people with both job and residence
MATCH (p)-[:knows]->(friend:Person) -- Same p: their social connections
RETURN *
Regole e limitazioni di ambito critiche:
-- ✅ Backward references work
MATCH (p:Person)
LET adult = p.birthday < 20061231 -- Can reference p from previous statement
RETURN *
-- ❌ Forward references don't work
LET adult = p.birthday < 20061231 -- Error: p not yet defined
MATCH (p:Person)
RETURN *
-- ❌ Variables in same LET statement can't reference each other
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName,
greeting = 'Hello, ' || name -- Error: name not visible yet
RETURN *
-- ✅ Use separate statements for dependent variables
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName
LET greeting = 'Hello, ' || name -- Works: name now available
RETURN *
Visibilità delle variabili nelle query complesse:
-- Variables remain visible until overridden or query ends
MATCH (p:Person) -- p available from here
LET gender = p.gender -- gender available from here
MATCH (p)-[:knows]->(e:Person) -- p still refers to original person
-- e is new variable for managed employee
RETURN p.firstName AS manager, e.firstName AS friend, gender
Attenzione
Le variabili nella stessa istruzione non possono fare riferimento l'una all'altra (tranne nei modelli a grafo). Usare istruzioni separate per la creazione di variabili dipendenti.
Tecniche avanzate di aggregazione
GQL supporta due tipi distinti di aggregazione per l'analisi dei dati tra gruppi e raccolte: aggregazione verticale con GROUP BY e aggregazione orizzontale su modelli a lunghezza variabile.
Aggregazione verticale con GROUP BY
L'aggregazione verticale (coperta in RETURN con GROUP BY) raggruppa le righe in base ai valori condivisi e calcola le aggregazioni all'interno di ogni gruppo:
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN c.name AS companyName,
count(*) AS employee_count,
avg(p.birthday) AS avg_birth_year
GROUP BY companyName
Questo approccio crea una riga di risultato per ogni azienda, aggregando tutti i dipendenti all'interno di ogni gruppo.
Aggregazione orizzontale con variabili di elenco di gruppi
L'aggregazione orizzontale calcola le aggregazioni sulle raccolte associate a modelli a lunghezza variabile. Quando si usano bordi a lunghezza variabile, la variabile di arco diventa una variabile elenco di gruppi che contiene tutti i bordi in ogni percorso corrispondente:
-- Group list variable 'edges' enables horizontal aggregation
MATCH (p:Person)-[edges:knows]->{2,4}(friend:Person)
RETURN p.firstName || ' ' || p.lastName AS person_name,
friend.firstName || ' ' || friend.lastName AS friend_name,
size(edges) AS degrees_of_separation,
avg(edges.creationDate) AS avg_connection_age,
min(edges.creationDate) AS oldest_connection
Annotazioni
Questa query non è ancora supportata (problema noto).
Differenze principali:
- L'aggregazione verticale riepiloga tra righe , o - raggruppa righe e riepiloga tra righe in ogni gruppo
- L'aggregazione orizzontale riepiloga gli elementi all'interno di singole raccolte perimetrali
- Le variabili elenco di gruppi provengono solo da modelli di arco a lunghezza variabile
Contesti di associazione dei bordi a lunghezza variabile
Comprendere il modo in cui le variabili perimetrali si associano nei modelli a lunghezza variabile è fondamentale:
Durante la corrispondenza dei criteri (contesto singleton):
-- Edge variable 'e' refers to each individual edge during filtering
MATCH (p:Person)-[e:knows WHERE e.creationDate > zoned_datetime('2000-01-01T00:00:00Z')]->{2,4}(friend:Person)
-- 'e' is evaluated for each edge in the path during matching
RETURN *
Nelle espressioni dei risultati (contesto di gruppo):
-- Edge variable 'edges' becomes a list of all qualifying edges
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)
RETURN size(e) AS num_edges, -- Number of edges in path
e[0].creationDate AS first_edge, -- First edge in path
avg(e.creationDate) AS avg_age -- Horizontal aggregation
Annotazioni
Questa query non è ancora supportata (problema noto).
Combinazione di aggregazioni verticali e orizzontali
È possibile combinare entrambi i tipi di aggregazione in modelli di analisi sofisticati:
-- Find average connection age by city pairs
MATCH (p1:Person)-[:isLocatedIn]->(c1:City)
MATCH (p2:Person)-[:isLocatedIn]->(c2:City)
MATCH (p1)-[e:knows]->{1,3}(p2)
RETURN c1.name AS city1,
c2.name AS city2,
count(*) AS connection_paths, -- Vertical: count paths per city pair
avg(size(e)) AS avg_degrees, -- Horizontal then vertical: path lengths
avg(avg(e.creationDate)) AS avg_connection_age -- Horizontal then vertical: connection ages
GROUP BY city1, city2
Annotazioni
Questa query non è ancora supportata (problema noto).
Suggerimento
L'aggregazione orizzontale ha sempre la precedenza sull'aggregazione verticale. Per convertire un elenco di gruppi in un elenco regolare, usare collect_list(edges).
Annotazioni
Per informazioni dettagliate sulle funzioni di aggregazione, vedere Espressioni e funzioni GQL.
Strategie di gestione degli errori
Comprendere i modelli di errore comuni consente di scrivere query affidabili.
Gestire correttamente i dati mancanti:
MATCH (p:Person)
-- Use COALESCE for missing properties
LET displayName = coalesce(p.firstName, p.lastName, 'Unknown')
LET contact = coalesce(p.locationIP, p.browserUsed, 'No info')
RETURN *
Usare controlli Null espliciti:
MATCH (p:Person)
-- Be explicit about null handling
FILTER p.id IS NOT NULL AND p.id > 0
-- Instead of just: FILTER p.id > 0
RETURN *
Informazioni aggiuntive
Codici GQLSTATUS
Come illustrato nella sezione sui risultati della query, GQL segnala informazioni dettagliate sullo stato relative all'esito positivo o potenziale dell'esecuzione. Per l'elenco completo, vedere le informazioni di riferimento sui codici di stato GQL .
Parole riservate
GQL riserva determinate parole chiave che non è possibile usare come identificatori come variabili, nomi di proprietà o nomi di etichetta. Per l'elenco completo, vedere le informazioni di riferimento sulle parole riservate GQL .
Se è necessario usare parole riservate come identificatori, eseguirne l'escape con backticks: `match`, `return`.
Per evitare l'escape di parole riservate, usare questa convenzione di denominazione:
- Per gli identificatori a parola singola, aggiungere un carattere di sottolineatura:
:Product_ - Per gli identificatori di più parole, usare camelCase o PascalCase:
:MyEntity,:hasAttribute,textColor
Passaggi successivi
Dopo aver compreso i concetti fondamentali di GQL, ecco il percorso di apprendimento consigliato:
Continuare a creare le competenze di GQL
Per principianti:
- Provare la guida introduttiva - Seguire l'esercitazione pratica per un'esperienza pratica
- Esercitazione sulle query di base : provare gli esempi di questa guida con i propri dati
- Informazioni sui modelli di grafo - Gestire la sintassi completa dei modelli
- Esplorare i tipi di dati - Informazioni sui valori E sui tipi di valore GQL
Per gli utenti esperti:
- Espressioni avanzate - Espressioni e funzioni GQL master
- Progettazione dello schema - Learn GQL graph types and constraints
- Esplorare i tipi di dati - Informazioni sui valori E sui tipi di valore GQL
Materiali di riferimento
Tenere a portata di mano questi riferimenti per ricerche rapide:
- Riferimento rapido per GQL - Riferimento rapido alla sintassi
- Codici di stato GQL - Informazioni di riferimento sul codice di errore completo
- Parole riservate GQL - Elenco completo di parole chiave riservate
Esplorare Microsoft Fabric
Informazioni sulla piattaforma:
- Modelli di dati dei gragrafi - Informazioni sui concetti e la modellazione dei gra gragrafi
- Grafico e database relazionali : scegliere l'approccio corretto
- Provare Gratuitamente Microsoft Fabric - Esperienza pratica
- Esercitazioni end-to-end - Scenari di apprendimento completi
Collabora subito
- Condividere commenti e suggerimenti - Migliorare la documentazione e gli strumenti
- Partecipare alla community : connettersi con altri professionisti del database a grafo
- Rimanere aggiornati - Seguire gli annunci di Microsoft Fabric per le nuove funzionalità
Suggerimento
Iniziare con l'esercitazione di avvio rapido se si preferisce imparare seguendo questa procedura o approfondire i modelli di grafo se si vuole prima gestire il linguaggio di query.
Contenuti correlati
Altri dettagli sugli argomenti chiave:
- Esempio di schema di social network - Esempio di lavoro completo dello schema del grafo
- Modelli di grafo GQL - Sintassi completa dei modelli e tecniche avanzate di corrispondenza
- Espressioni e funzioni GQL - Tutti i tipi di espressione e le funzioni predefinite
- Tipi di gragrafi GQL - Tipi e vincoli del grafo
- Valori e tipi valore GQL - Informazioni di riferimento complete sul sistema dei tipi e gestione dei valori
Riferimenti rapidi:
- Riferimento rapido per GQL - Riferimento rapido alla sintassi
- Codici di stato GQL - Informazioni di riferimento sul codice di errore completo
- Parole riservate GQL - Elenco completo di parole chiave riservate
Grafico in Microsoft Fabric:
- Modelli di dati dei gragrafi - Informazioni sui concetti e la modellazione dei gra gragrafi
- Grafico e database relazionali - Differenze e quando usare ogni database
- Provare Gratuitamente Microsoft Fabric
- Esercitazioni “end-to-end” in Microsoft Fabric