Informazioni di riferimento rapido su GQL

Questo articolo è un riferimento rapido per la sintassi GQL (Graph Query Language) per il grafico in Microsoft Fabric. Usalo per ricordare sintassi e valori predefiniti. Per una spiegazione end-to-end, consulta la guida linguistica GQL; ogni sezione si collega al riferimento focalizzato che possiede tutti i dettagli.

Annotazioni

Questo articolo usa principalmente il set di dati del grafo di esempio di social network. Fornisce anche alcuni esempi che usano il set di dati Adventure Works dell'esercitazione sul grafo.

Struttura di interrogazione

Le query GQL usano una sequenza di istruzioni che definiscono i dati da ottenere dal grafico, come elaborarli e come visualizzare i risultati. Ogni istruzione ha uno scopo specifico e insieme creano una pipeline lineare che corrisponde ai dati del grafico e li trasforma passo dopo passo.

Flusso di query tipico:
Una query GQL viene in genere avviata specificando il modello di grafo a cui trovare la corrispondenza. Usa quindi istruzioni facoltative per la creazione di variabili, il filtro, l'ordinamento, l'impaginazione e l'output dei risultati.

Esempio:

MATCH (n:Person)-[:knows]->(m:Person) 
LET fullName = n.firstName || ' ' || n.lastName 
FILTER m.gender = 'female' 
ORDER BY fullName ASC 
OFFSET 10
LIMIT 5 
RETURN fullName, m.firstName

Composizione delle dichiarazioni:

Importante

Le istruzioni formano una pipeline ordinata e non possono essere riorganizzate arbitrariamente. Vedere l'articolo sulle limitazioni correnti.

  • MATCH : specificare i modelli di grafico da trovare.
  • LET : definire le variabili dalle espressioni.
  • FOR – Espandere un elenco in righe.
  • CALL – Eseguire una sottoquery inline e aggiungere le colonne restituite.
  • FILTER : mantenere le condizioni di corrispondenza delle righe.
  • WHEN – Instradare ogni riga di input al primo ramo condizionale corrispondente.
  • ORDER BY : ordinare i risultati.
  • OFFSET : ignorare molte righe.
  • LIMIT : limitare il numero di righe.
  • RETURN : restituisce i risultati finali.
  • NEXT – Avviare un'altra fase di query utilizzando le colonne restituite dalla fase precedente.

Ogni istruzione si basa su quella precedente, in modo da perfezionare e modellare in modo incrementale l'output della query. Usa UNION, UNION DISTINCT, oppure UNION ALL per combinare blocchi completi di interrogazione. Per altre informazioni su ogni istruzione, vedere le sezioni seguenti.

Comandi di query

MATCH

Trovare modelli di grafo nei dati.

Sintassi:

MATCH <graph pattern> [ WHERE <predicate> ]
...

Esempio:

MATCH (n:Person)-[:knows]-(m:Person) WHERE n.birthday > 2000
RETURN *

Per altre informazioni sull'istruzione MATCH , vedere i modelli graph.

LASCIARE

Creare variabili usando espressioni.

Sintassi:

LET <variable> = <expression>, <variable> = <expression>, ...
...

Esempio:

MATCH (n:Person)
LET fullName = n.firstName || ' ' || n.lastName
RETURN fullName

Per altre informazioni sull'istruzione LET , vedere la guida al linguaggio GQL.

FOR

Espande una lista in righe e opzionalmente restituisce la posizione di ogni elemento.

Sintassi:

FOR <variable> IN <list_expression>
  [ WITH OFFSET <offset_variable> | WITH ORDINALITY <ordinality_variable> ]
...

Esempio:

FOR value IN [10, 20] WITH OFFSET index
RETURN value, index

WITH OFFSET inizia da 0. WITH ORDINALITY inizia da 1.

Per altre informazioni sull'istruzione FOR , vedere la guida al linguaggio GQL.

CALL

Esegue una sottoquery inline per ogni riga di input. Le variabili già nell'ambito sono implicitamente disponibili all'interno della sottoquery.

Sintassi:

[ OPTIONAL ] CALL {
  <query statements>
  RETURN <columns>
}
...

Delle variabili create all'interno della sottoquery, solo le colonne della sua istruzione finale RETURN diventano disponibili al di fuori di essa. Ordinary CALL elimina una riga esterna quando la sottoquery non restituisce righe e la moltiplica quando la sottoquery restituisce più righe. OPTIONAL CALL preserva una riga esterna con NULL colonne di sottoquery quando la sottoquery non restituisce righe.

MATCH (p:Person)
CALL {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN count(*) AS friendCount
}
RETURN p.firstName, friendCount

Per maggiori informazioni sulle sottoquery inline, consulta la guida linguistica GQL.

FILTRO

Mantiene le righe che corrispondono alle condizioni.

Sintassi:

FILTER [ WHERE ] <predicate>
...

Esempio:

MATCH (n:Person)-[:knows]->(m:Person)
FILTER WHERE n.birthday > m.birthday
RETURN *

Per altre informazioni sull'istruzione FILTER , vedere la guida al linguaggio GQL.

ORDINA PER

Ordina i risultati.

Sintassi:

ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ...
...

Esempio:

MATCH (n:Person)
RETURN *
ORDER BY n.lastName ASC NULLS LAST, n.firstName ASC

La posizione nulla è indipendente dalla direzione di ordinamento. Il valore predefinito è NULLS LAST sia per che DESCper ; specificare NULLS FIRST di mettere i valori nulli prima dei valori ASC non nulli.

Importante

L'ordine richiesto delle righe è garantito solo immediatamente dopo un'affermazione ORDER BY precedente. Le istruzioni seguenti (se presenti) non sono garantite per mantenere tale ordine.

Per altre informazioni sull'istruzione ORDER BY , vedere la guida al linguaggio GQL.

OFFSET/LIMIT

Ignorare le righe e limitare il numero di risultati.

Sintassi:

OFFSET <offset> [ LIMIT <limit> ]
LIMIT <limit>
...

Esempio:

MATCH (n:Person)
ORDER BY n.birthday
OFFSET 10 LIMIT 20
RETURN n.firstName || ' ' || n.lastName AS name, n.birthday

Per altre informazioni sulle OFFSET istruzioni e LIMIT , vedere la guida al linguaggio GQL.

RETURN

Restituisce i risultati finali.

Sintassi:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], ...

Esempio:

MATCH (n:Person)
RETURN n.firstName, n.lastName

Per altre informazioni sull'istruzione RETURN , vedere la guida al linguaggio GQL.

NEXT

Inizia un'altra fase di interrogazione. Solo le colonne restituite dalla fase precedente sono disponibili dopo NEXT.

Sintassi:

<query stage>
RETURN <columns>
NEXT
<query stage>

Esempio:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Entrambi i livelli possono contenere un'unione di blocchi di interrogazione. L'unione viene valutata all'interno di quella fase prima che la sua uscita attraversi il NEXT confine.

Per maggiori informazioni su NEXT, consulta la guida linguistica GQL.

Istruzioni condizionali

Instrada ogni riga di input al primo WHEN ramo il cui predicato valuta a TRUE.

Sintassi:

WHEN <predicate> THEN <linear query statement or { query statements }>
[ WHEN <predicate> THEN <linear query statement or { query statements }> ... ]
[ ELSE <linear query statement or { query statements }> ]

I predicati devono essere booleani e vengono valutati in ordine. FALSE e UNKNOWN cadono al ramo successivo. Se nessun branch corrisponde e non ELSEc'è , la riga di input viene omessita. I predicati dopo la prima corrispondenza e i corpi di ramo non selezionati non vengono valutati.

RETURN 'Alice' AS name, 19900101u AS birthday
NEXT
WHEN birthday < 20000101u THEN
  RETURN name, 'Before 2000' AS era
ELSE
  RETURN name, '2000 or later' AS era

Tutti i rami devono restituire gli stessi nomi di colonna con tipi di dati compatibili. Racchiudere un ramo con apparecchi quando contiene una procedura annidata.

Per ulteriori informazioni, vedi Enunciati condizionali.

UNION

Combina l'output dei blocchi completi di interrogazione.

Sintassi:

<query block>
UNION [ DISTINCT | ALL ]
<query block>

Svela UNION e UNION DISTINCT rimuovi le righe duplicate. UNION ALL preserva le righe duplicate. Ogni blocco di query deve restituire lo stesso insieme di nomi di colonne con tipi di dati compatibili.

Per maggiori informazioni sui sindacati, consulta la guida linguistica GQL.

Modelli di grafo

I modelli di grafo descrivono la struttura del grafico a cui trovare una corrispondenza.

Modelli di nodo

Nei database a grafo usare i nodi per rappresentare entità, ad esempio persone, prodotti o posizioni.

I modelli di nodo descrivono come trovare le corrispondenze tra i nodi nel grafico. È possibile filtrare in base all'etichetta o alle variabili di associazione.

(n)              -- Any node
(n:Person)       -- Node with Person label  
(n:City&Place)   -- Node with City AND Place label
(:Person)        -- Person node, don't bind variable

Per altre informazioni sui modelli di nodo, vedere i modelli di grafo.

Modelli di arco

I modelli di arco specificano le relazioni tra i nodi, tra cui direzione e tipo di arco. Nei database a grafo, un bordo rappresenta una connessione o una relazione tra due nodi.

<-[e]-             -- Incoming edge
-[e]->             -- Outgoing edge
-[e]-              -- Any edge
-[e:knows]->       -- Edge with label ("relationship type")
-[e:knows|likes]-> -- Edges with different labels
-[:knows]->        -- :knows edge, don't bind variable

Per altre informazioni sui modelli di arco, vedere i modelli di grafo.

Espressioni di etichetta

Le espressioni di etichetta consentono di associare i nodi con combinazioni di etichette specifiche usando operatori logici.

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

Per altre informazioni sulle espressioni di etichetta, vedere i modelli graph.

Modelli di percorso

I modelli di percorso descrivono gli attraversamenti attraverso il grafico, inclusi i conteggi degli hop e le associazioni di variabili.

(a)-[:knows|likes]->{1,3}(b)        -- 1-3 hops via knows/likes
p=()-[:knows]->()                   -- Bind a path variable
MATCH REPEATABLE ELEMENTS (a)->(b)  -- Explicit default match mode
MATCH DIFFERENT EDGES (a)->(b), (a)->(c)
MATCH ALL TRAIL (a)->{1,4}(b)       -- Every edge-unique path
MATCH p = ANY SHORTEST (a)->{1,4}(b) -- One shortest path per endpoint pair

WALK è la modalità di percorso predefinita e consente la ripetizione di nodi e archi. TRAIL Evita la ripetizione dei bordi. SIMPLE previene la ripetizione dei nodi tranne che per la chiusura del ciclo primo-ultimo, e ACYCLIC impedisce tutti i nodi ripetuti. Entrambe le modalità uniche per nodo impediscono anche la ripetizione degli spigoli perché il riutilizzo dei bordi ripeterebbe i nodi endpoint. ALL è la ricerca del percorso predefinita. ANY SHORTEST restituisce un percorso più breve per ogni coppia sorgente-destinazione e non sceglie deterministicamente tra i percorsi legati.

I quantificatori supportati includono fissi {n}, limitati {m,n} e {,n}, e non limitati {m,}, *, e +. I pattern non limitati ALL WALK non sono supportati; usa una modalità path termining. L'inlimitato ANY SHORTEST WALK presenta restrizioni aggiuntive di forma e di valore di percorso. Per dettagli, vedi i pattern grafici GQL.

Per altre informazioni sui modelli di percorso, vedere i modelli di grafo.

Più modelli

Usare più modelli per trovare corrispondenze tra strutture di gragrafi complesse e non lineari in una singola query.

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

Per altre informazioni su più modelli, vedere i modelli di grafo.

Valori e tipi valore

Tipi di base

I tipi di base sono valori di dati primitivi come stringhe, numeri, valori booleani e datetime.

STRING           -- 'hello', "world"
INT64            -- 42, -17
FLOAT64          -- 3.14, -2.5e10, -17d
BOOL             -- TRUE, FALSE, UNKNOWN
ZONED DATETIME   -- ZONED_DATETIME('2023-01-15T10:30:00Z')

Il d suffisso or D crea un letterale approssimativo FLOAT64 . Un esponente senza suffisso crea anche un FLOAT64 valore. I f suffissi e F letterali attualmente non sono supportati.

Per altre informazioni sui tipi di base, vedere GQL values and value types .For more information about basic types, see GQL values and value types.

Tipi valore di riferimento

I tipi di valore di riferimento sono nodi e archi usati come valori nelle query.

NODE             -- Node reference values
EDGE             -- Edge reference values

Per altre informazioni sui tipi valore di riferimento, vedere Valori e tipi valore GQL.

Tipi di raccolta

I tipi di raccolta raggruppano più valori, ad esempio elenchi e percorsi.

LIST<INT64>      -- [1, 2, 3]
LIST<STRING>     -- ['a', 'b', 'c']
PATH             -- Path values

Per altre informazioni sui tipi di raccolta, vedere GQL values and value types .For more information about collection types, see GQL values and value types.

Tipi materiali e nullabili

Ogni tipo di valore è nullable (include il valore Null) o il materiale (lo esclude). Per impostazione predefinita, i tipi sono nullable a meno che non si specifichi NOT NULLin modo esplicito .

STRING NOT NULL  -- Material (Non-nullable) string type
INT64            -- Nullable (default) integer type

Espressioni e operatori

Condizionale

Le espressioni semplici CASE confrontano un'espressione con uno o più valori.

CASE expr WHEN val THEN val ELSE val END -- Simple CASE
NULLIF(a, b)                           -- NULL if a = b

Le espressioni cercate CASE WHEN <predicate> non sono supportate. Usa un'istruzione condizionale per instradare le righe in base ai predicati.

Per altre informazioni sulle espressioni condizionali, vedere espressioni e funzioni GQL.

Comparison

Gli operatori di confronto confrontano i valori e controllano l'uguaglianza, l'ordinamento o i valori Null.

=, <>, <, <=, >, >=              -- Standard comparison
IS NULL, IS NOT NULL             -- Null checks

Per altre informazioni sui predicati di confronto, vedere espressioni e funzioni GQL.

Logical

Gli operatori logici combinano o negano condizioni booleane nelle query.

AND, OR, NOT, XOR               -- Boolean logic

Per altre informazioni sulle espressioni logiche, vedere espressioni e funzioni GQL.

EXISTS

Verifica se una sottoquery procedura-forma restituisce almeno una riga.

EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}

EXISTS restituisce un valore booleano non nullo. Usalo NOT EXISTS per testare che la sottoquery non restituisca righe. Puoi usare il risultato in WHERE o FILTER, LET, RETURN, ORDER BY, e aggregare il filtro o le espressioni sorgente. EXISTS non è supportato all'interno di un filtro di predicati di lista.

Importante

I moduli basati solo su pattern grafici come EXISTS { (p)-[:knows]->(friend) } e EXISTS ((p)-[:knows]->(friend)) non sono supportati. Usa il modulo di procedura con MATCH mostrato nell'esempio precedente.

Caution

Un aggregato non raggruppato come RETURN count(*) come restituisce una riga anche quando nessun pattern corrisponde. Poiché EXISTS testa le righe, quella forma valuta a TRUE.

Per maggiori informazioni su EXISTS, vedi Sottoquery di Esistenza.

Arithmetic

Gli operatori aritmetici eseguono calcoli sui numeri.

+, -, *, /                       -- Basic arithmetic operations
1.00m / 8.00m                    -- Exact result: 0.1250m

Per altre informazioni sulle espressioni aritmetiche, vedere espressioni e funzioni GQL.

Modelli di stringa

I predicati dei criteri di stringa corrispondono a sottostringhe, prefissi o suffissi nelle stringhe.

n.firstName CONTAINS 'John'          -- Has substring
n.browserUsed STARTS WITH 'Chrome'   -- Starts with prefix
n.locationIP ENDS WITH '.1'          -- Ends with suffix
MSFT.REGEXP_LIKE(n.firstName, '^jo', 'i') -- RE2 regular expression

Per altre informazioni sui predicati dei criteri di stringa, vedere espressioni e funzioni GQL.

Elencare le operazioni

Elencare le operazioni testano l'appartenenza, gli elementi di accesso e la lunghezza dell'elenco delle misure.

n.gender IN ['male', 'female']    -- Membership test
n.tags[0]                        -- First element
size(n.tags)                     -- List length
ALL(x IN n.tags WHERE x <> '')   -- Every element matches
ANY(x IN n.tags WHERE x = 'gql') -- At least one element matches
NONE(x IN n.tags WHERE x = '')   -- No element matches
SINGLE(x IN n.tags WHERE x = 'gql') -- Exactly one element matches

Le funzioni predicate elencare restituiscono TRUE, FALSE, oppure UNKNOWN secondo i risultati del filtro. Per una lista vuota, ALL e NONE return TRUE, mentre ANY e SINGLE return FALSE. Una lista di sorgenti nulle restituisce UNKNOWN.

Il legame degli elementi è locale al filtro e può ombreggiare una variabile esterna. Gli aggregati su quel binding locale e EXISTS le sottoquery all'interno del filtro non sono supportati.

Per ulteriori informazioni, vedi Elenco delle funzioni predicate.

Accesso alle proprietà

L'accesso alle proprietà ottiene il valore di una proprietà da un nodo o un bordo.

n.firstName                      -- Property access

Per altre informazioni sull'accesso alle proprietà, vedere espressioni e funzioni GQL.

Functions

Usa funzioni integrate per trasformare valori, ispezionare elementi del grafo e aggregare righe.

Funzioni numeriche

Le funzioni numeriche calcolano valori numerici o producono intervalli interi.

abs(value)                       -- Absolute value; preserves the numeric type
power(base, exponent)            -- Exponentiation; returns DOUBLE
sin(radians), cos(radians)       -- Trigonometric functions
asin(value), acos(value)         -- Inverse functions; value must be in [-1, 1]
degrees(radians)                 -- Convert radians to degrees
radians(degrees)                 -- Convert degrees to radians
range(start, end)                -- Integer range with step 1
range(start, end, step)          -- Integer range with a nonzero step

Altre funzioni trigonometriche supportate sono TAN, COT, ATAN, SINH, COSH, e TANH. Tranne che ABS per e RANGE, queste funzioni numeriche restituiscono DOUBLE.

Scopri di più sulle funzioni numeriche nelle espressioni e funzioni GQL.

Funzioni di aggregazione

Le funzioni di aggregazione calcolano i valori di riepilogo per i gruppi di righe (aggregazione verticale) o sugli elementi di un elenco di gruppi (aggregazione orizzontale).

count(*)                         -- Count all rows
count(expr)                      -- Count non-null values
sum(p.birthday)                  -- Sum values
avg(p.birthday)                  -- Average
min(p.birthday), max(p.birthday) -- Minimum and maximum values
collect_list(p.firstName)        -- Collect inputs, including nulls
collect_one(p.firstName)         -- Select one non-null value
collect_elements(p.roles)        -- Concatenate list-valued inputs
count(DISTINCT expr)             -- Remove duplicate expression values
count(*) FILTER (WHERE predicate LIMIT 10) -- Filter and limit this aggregate

Senza raggruppare le colonne, una query aggregata senza righe di input restituisce per , una lista vuota per COLLECT_LIST e COLLECT_ELEMENTS, e nulla per SUM, AVG, MIN, MAX, e COLLECT_ONE.COUNT0 Un argomento a lista di gruppi rende l'aggregato orizzontale.

Altre informazioni sulle funzioni di aggregazione nelle espressioni e nelle funzioni GQL.

Funzioni stringa

Le funzioni stringa consentono di usare e analizzare i valori stringa.

char_length(s)                   -- String length
upper(s), lower(s)               -- Unicode case mapping
casefold(s)                      -- Unicode caseless form
normalize(s)                     -- Normalize a string to NFC
normalize(s, NFD)                -- Normalize a string to NFD
trim(s)                          -- Trim spaces
trim(leading '_' from s)         -- Trim one custom byte
string_join(list)                -- Join with ", "
string_join(list, delimiter)     -- Join with a custom delimiter
MSFT.REGEXP_COUNT(s, pattern)    -- Count RE2 matches
MSFT.REGEXP_INSTR(s, pattern)    -- Find a zero-based match position
MSFT.REGEXP_SUBSTR(s, pattern)   -- Return matching text
MSFT.REGEXP_REPLACE(s, pattern, replacement) -- Replace matches

I pattern regex, le sostituzioni e le opzioni devono essere letterali. Per firme, flag e comportamento nullo, vedi Funzioni stringa.

Funzioni di elenco

Le funzioni elenco consentono di usare elenchi, ad esempio il controllo della lunghezza o delle dimensioni di taglio.

size(list)                       -- List length
trim(list, n)                    -- Trim a list to at most n elements

Per altre informazioni sulle funzioni di elenco, vedere Espressioni e funzioni GQL.

Funzioni del grafo

Le funzioni del grafo consentono di ottenere informazioni da nodi, percorsi e archi.

labels(node)                     -- Get node labels
element_id(node_or_edge)         -- Get an opaque element identifier
nodes(path)                      -- Get path nodes
edges(path)                      -- Get path edges
elements(path)                   -- Get all path nodes and edges
path_length(path)                -- Get number of edges in a path

Per altre informazioni sulle funzioni del grafo, vedere Espressioni e funzioni GQL.

Funzioni temporali

Le funzioni temporali consentono di usare valori di data e ora.

CURRENT_TIMESTAMP                -- Get the current zoned datetime
ZONED_DATETIME(string)           -- Parse an ISO 8601 zoned datetime
DURATION(string)                 -- Parse an ISO 8601 day-time duration

Per altre informazioni sulle funzioni temporali, vedere Espressioni e funzioni GQL.

Funzioni generica

Le funzioni generice consentono di usare i dati in modi comuni.

coalesce(expr1, expr2, ...)    -- Get the first non-null value
to_json_string(value)          -- Convert value to JSON string
nullif(a, b)                   -- NULL if a = b, else a

Per altre informazioni sulle funzioni generiche, vedere Espressioni e funzioni GQL.

Esempi orientati al compito

Usa gli articoli tutorial quando hai bisogno di schemi di query completi e pronti ad adattarsi:

Contenuti correlati

  • Ultimo aggiornamento: