Condividi tramite

Espressioni, predicati e funzioni GQL

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.

Le espressioni GQL consentono di eseguire calcoli, confronti e trasformazioni sui dati all'interno delle query. In combinazione con le funzioni predefinite, le espressioni offrono potenti strumenti per l'elaborazione, il filtro e l'analisi dei dati nelle query a grafo.

Literals

I valori letterali sono espressioni semplici che restituiscono direttamente il valore dichiarato. I valori letterali di ogni tipo di valore vengono illustrati in dettaglio nei valori GQL e nei tipi valore.

Esempio:

1
1.0d
TRUE
"Hello, graph!"
[ 1, 2, 3 ]
NULL

Per una sintassi letterale dettagliata per ogni tipo di dati, vedere Valori GQL e tipi valore.

Predicates

I predicati sono espressioni booleane, comunemente usate per filtrare i risultati nelle query GQL. Restituiscono TRUE, FALSEo UNKNOWN (null).

Attenzione

Se usato come filtro, i predicati mantengono solo gli elementi, per i quali il predicato restituisce TRUE.

Predicati di confronto

Confrontare i valori usando questi operatori:

  • = (uguale)
  • <> (diverso da)
  • < (minore di)
  • > (maggiore di)
  • <= (minore o uguale)
  • >= (maggiore o uguale)

GQL usa la logica a tre valori in cui i confronti con valori Null restituiscono UNKNOWN:

Expression Result
5 = 5 TRUE
5 = 3 FALSE
5 = NULL UNKNOWN
NULL = NULL UNKNOWN

Per un comportamento di confronto specifico, vedere la documentazione per ogni tipo di valore nei valori GQL e nei tipi valore.

Esempio:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915
RETURN p.firstName

Regole di coercizione numerica:

In ordine di precedenza:

  1. Le espressioni di confronto che includono argomenti di tipi numerici approssimativi comproprigliano tutti gli argomenti di un tipo numerico approssimativo.
  2. Le espressioni di confronto che includono argomenti di tipi integer con segno e senza segno coercino tutti gli argomenti in modo che siano di un tipo integer con segno.

Espressioni logiche

Combinare condizioni con operatori logici:

  • AND (entrambe le condizioni true)
  • OR (entrambe le condizioni true)
  • NOT (nega condizione)

Esempio:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915 AND p.firstName = 'John'
RETURN p.firstName || ' ' || p.lastName AS fullName

Predicati di esistenza delle proprietà

Per verificare se esistono proprietà, puoi utilizzare:

p.locationIP IS NOT NULL
p.browserUsed IS NULL

Annotazioni

Tentare di accedere a una proprietà nota inesistente comporta un errore di sintassi. L'accesso a una proprietà potenzialmente inesistente valuta a null. La determinazione se una proprietà sia nota o potenzialmente inesistente avviene in base al tipo di nodo o spigolo a cui si accede.

Elencare i predicati di appartenenza

Verificare se i valori si trovano negli elenchi:

p.firstName IN ['Alice', 'Bob', 'Charlie']
p.gender NOT IN ['male', 'female']

Predicati del modello di stringa

Trova la corrispondenza tra stringhe usando criteri di ricerca:

p.firstName CONTAINS 'John'
p.browserUsed STARTS WITH 'Chrome'
p.locationIP ENDS WITH '.1'

Espressioni aritmetiche

Usare operatori aritmetici standard con valori numerici:

  • + (addizione)
  • - (sottrazione)
  • * (moltiplicazione)
  • / (divisione)

Gli operatori aritmetici seguono convenzioni matematiche generali.

Precedenza:

Gli operatori in genere seguono le regole di precedenza degli operatori stabilite, ad esempio * prima +di . Usare le parentesi per controllare l'ordine di valutazione in base alle esigenze.

Esempio:

(p.birthday < 20050915 OR p.birthday > 19651231) AND p.gender = 'male'

Regole di coercizione:

In ordine di precedenza:

  1. Le espressioni aritmetiche che coinvolgono argomenti di tipi numerici approssimativi restituiscono un risultato di un tipo numerico approssimativo.
  2. Le espressioni aritmetiche che coinvolgono argomenti di tipi integer con segno e senza segno restituiscono un risultato di un tipo integer con segno.

Esempio:

LET birth_year = p.birthday / 10000
RETURN birth_year

Accesso alle proprietà

Accedere alle proprietà usando la notazione del punto:

p.firstName
edge.creationDate

Elencare l'accesso

Accedere a elementi elenco usando l'indicizzazione in base zero:

interests[0]    -- first element
interests[1]    -- second element

Funzioni predefinite

GQL supporta varie funzioni predefinite per l'elaborazione e l'analisi dei dati.

Funzioni di aggregazione

Le funzioni di aggregazione vengono usate per valutare un'espressione su un set di righe e ottenere un valore finale del risultato combinando i valori calcolati per ogni riga. Le funzioni di aggregazione seguenti sono supportate per il grafico in Microsoft Fabric:

  • count(*) - conta le righe
  • sum(expression) - somma valori numerici
  • avg(expression) - medie valori numerici
  • min(expression) - trova il valore minimo
  • max(expression) - trova il valore massimo
  • collect_list(expression) - raccoglie i valori in un elenco

In generale, le funzioni di aggregazione ignorano i valori Null e restituiscono sempre un valore Null quando non vengono forniti valori di input materiali. È possibile usare coalesce per ottenere un valore predefinito diverso: coalesce(sum(expr), 0). L'unica eccezione è la count funzione di aggregazione, che conta sempre i valori non Null forniti, restituendo 0 se non sono presenti. Usare count(*) anche per includere valori Null nel conteggio.

Le funzioni di aggregazione vengono usate in tre modi diversi:

  • Per le aggregazioni di calcolo (verticale) su intere tabelle
  • Per le aggregazioni di calcolo (verticale) su tabelle secondarie determinate da una chiave di raggruppamento
  • Per l'elaborazione (orizzontale) aggregazioni sugli elementi di un elenco di gruppi

Aggregazioni verticali:

-- Vertical aggregate over whole table
MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year

-- Vertical aggregate with grouping
MATCH (p:Person)-[:isLocatedIn]->(c:City)
RETURN c.name, count(*) AS population, avg(p.birthday) AS average_birth_year
GROUP BY c.name

Aggregazioni orizzontali:

L'aggregazione orizzontale calcola le aggregazioni sugli elementi delle variabili dell'elenco di gruppi dai modelli a lunghezza variabile:

-- Horizontal aggregate over a group list variable
MATCH (p:Person)-[edges:knows]->{1,3}(:Person)
RETURN p.firstName, avg(edges.creationDate) AS avg_connection_date

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 una copertura completa delle tecniche di aggregazione, tra cui l'associazione dei bordi a lunghezza variabile e la combinazione di aggregazioni orizzontali/verticali, vedere Tecniche avanzate di aggregazione.

Funzioni stringa

  • char_length(string) - restituisce la lunghezza della stringa
  • upper(string)- restituisce una variante maiuscola della stringa specificata (solo US ASCII)
  • lower(string)- restituisce una variante minuscola della stringa specificata (solo US ASCII)
  • trim(string) - rimuove gli spazi vuoti iniziali e finali
  • string_join(list, separator) - unisce elementi elenco con separatore

Esempio:

MATCH (p:Person)
WHERE char_length(p.firstName) > 5
RETURN upper(p.firstName) AS name_upper

Funzioni del grafo

  • nodes(path) : restituisce nodi da un valore di percorso
  • edges(path) - restituisce i bordi da un valore di percorso
  • labels(node_or_edge) : restituisce le etichette di un nodo o di un bordo come elenco di stringhe

Esempio:

MATCH p=(:Company)<-[:workAt]-(:Person)-[:knows]-{1,3}(:Person)-[:workAt]->(:Company)
RETURN nodes(p) AS chain_of_colleagues

Funzioni di elenco

  • size(list) - restituisce le dimensioni di un valore di elenco
  • trim(list,n) - tagliare un elenco in modo che sia al massimo di dimensioni n

Esempio:

MATCH (p:Person)-[:hasInterest]->(t:Tag)
WHERE size(collect_list(t)) > 3
RETURN p.firstName, collect_list(t.name) AS interests

Funzioni temporali

  • zoned_datetime() - restituisce datetime con zona corrente
  • zoned_datetime("2025-09-12T10:10:52Z") : restituisce un valore datetime con zone specificato dall'argomento in formato ISO 8601

Esempio:

RETURN zoned_datetime() AS now

Funzioni generica

  • coalesce(value1, value2, ...) - restituisce il primo valore non Null

Esempio:

MATCH (p:Person)
RETURN coalesce(p.firstName, 'Unknown') AS display_name

Contenuti correlati

  • Last updated on