Valori e tipi valore GQL

Questo articolo fornisce informazioni di riferimento complete per i valori GQL e i tipi valore nel grafico in Microsoft Fabric.

Il linguaggio GQL supporta diversi tipi di valori, ad esempio numeri, stringhe ed elementi del grafo. Questi valori sono organizzati in set denominati tipi valore, che definiscono le operazioni che è possibile eseguire e il comportamento dei valori in contesti diversi. Comprendere il sistema dei tipi è essenziale per scrivere query corrette ed evitare errori di runtime.

Concetti chiave:

• I tipi valore possono essere nullable o material (non nullable), a seconda che includano o escludano il valore Null.
• I tipi valore non nullable vengono specificati sintatticamente come NOT NULL.
• Lo stesso valore può appartenere a più tipi valore (polimorfismo).
• Il valore Null è un membro di ogni tipo di valore nullable.

Modalità di organizzazione dei tipi valore

Tutti i tipi di valore rientrano in due categorie principali che fungono da scopi diversi nelle query:

• Tipi di valore predefiniti : incorporati nella lingua, ad esempio numeri, stringhe e valori booleani.
• Tipi valore costruiti : composti da altri tipi, ad esempio elenchi e percorsi.

I tipi valore predefiniti sono ulteriormente organizzati in categorie specializzate:

• Tipi valore booleano : valori True, false e sconosciuti per le operazioni logiche.
• Tipi di valori stringa di caratteri : dati di testo con supporto Unicode.
• Tipi di valore numerico : numeri interi e numeri a virgola mobile.
• Tipi di valori temporali : valori di data e ora con il supporto del fuso orario.
• Tipi di valore di riferimento : riferimenti a nodi e archi nel grafico.
• Tipi di valore irrilevanti : valori speciali come null e niente.

Funzionamento dell'uguaglianza e del confronto

Comprendere in che modo GQL confronta i valori è fondamentale per la scrittura di query efficaci, soprattutto quando si gestiscono filtri, ordinamenti e join.

Regole di confronto di base

• In genere è possibile confrontare i valori dello stesso tipo.
• Se entrambi i valori sono numeri, GQL li confronta con i loro valori numerici.
• È possibile confrontare solo i valori di riferimento che fanno riferimento allo stesso tipo di oggetto, ad esempio i riferimenti ai nodi con riferimenti a nodi e riferimenti perimetrali con riferimenti ai bordi.

Gestione dei valori Null nei confronti

Quando si confronta un valore con Null, il risultato è sempre UNKNOWN. La gestione dei valori Null segue i principi della logica a tre valori. ORDER BY gestisce la posizione dei nulli separatamente dai confronti. Di default, i valori nulli ordinano per ultimo sia in ordine ascendente che in quello decrescente. Usa NULLS FIRST o NULLS LAST controlla esplicitamente la loro posizione.

Distinzione vs. uguaglianza

Alcune istruzioni non testano l'uguaglianza, ma piuttosto testano la distinctness. Comprendere la differenza è importante per le operazioni come DISTINCT e GROUP BY.

Il test di distinctness segue le stesse regole dell'uguaglianza con un'eccezione cruciale: NULL non è distinto da NULL. La distinctness differisce dai test di uguaglianza che coinvolgono NULL, che comportano UNKNOWNsempre .

Le istruzioni seguenti usano test di distinctness:

• RETURN DISTINCT: determina se due righe sono duplicate l'una dall'altra.
• GROUP BY: determina se due righe appartengono alla stessa chiave di raggruppamento durante l'aggregazione.

Due righe di una tabella sono distinte se è presente almeno una colonna in cui i valori di entrambe le righe sono distinti.

Tipi valore booleani

I valori booleani usano la logica a tre valori: TRUE, FALSEe UNKNOWN.

Funzionamento dell'uguaglianza:

Funzionamento del confronto:

FALSE è minore di TRUE. Qualsiasi confronto che coinvolge UNKNOWN i risultati in UNKNOWN.

Come scrivere valori letterali booleani:

• TRUE
• FALSE
• UNKNOWN oppure NULL

Sintassi del tipo:

BOOL [ NOT NULL ]

Tipi di valori stringa di caratteri

Le stringhe di caratteri sono sequenze di punti di codice Unicode (possono essere di lunghezza zero). La stringa di caratteri vuota non è identica al valore Null.

Funzionamento del confronto:

Le stringhe di caratteri vengono confrontate confrontando i valori scalari Unicode dei relativi punti di codice. Questo metodo di confronto viene talvolta definito regole UCS_BASIC di confronto.

Come scrivere valori letterali stringa:

Racchiudere i caratteri tra virgolette doppie (") o virgolette singole ('):

"Hello, World!"
'Guten Tag!'

Non è possibile specificare direttamente determinati caratteri di controllo Unicode nei valori letterali stringa. In particolare, tutti i caratteri delle classi Categoria Generale Unicode "Cc" e "Cn" non sono consentiti. Usare invece gli escape in stile \C:

GQL supporta anche l'escape in stile SQL raddoppiando i caratteri e " circostanti':

Sintassi del tipo:

STRING [ NOT NULL ]

Tipi numerici

Tipi numerici esatti

Graph supporta interi con e senza segno.

Funzionamento del confronto:

Il sistema confronta i valori numerici esatti compatibili in base al loro valore numerico.

Come scrivere valori letterali integer:

Sintassi del tipo:

INT [ NOT NULL ]
INT64 [ NOT NULL ]
UINT [ NOT NULL ]
UINT64 [ NOT NULL ]

INT e INT64 specificare lo stesso tipo numerico. Quindi, UINT e UINT64.

Tipi numerici approssimativi

Graph supporta numeri approssimativi che sono IEEE (Institute of Electrical and Electronics Engineers) numeri a virgola mobile compatibili con 754.

Funzionamento del confronto:

Il sistema confronta i valori numerici approssimati compatibili in base al loro valore numerico.

Come scrivere valori letterali a virgola mobile:

Considerazioni numeriche aggiuntive:

• Overflow e underflow: le operazioni intere che superano l'intervallo supportato producono un errore con stato 22003canonico GQL .
• Precisione: le operazioni a virgola mobile potrebbero perdere precisione a causa di limitazioni di rappresentazione IEEE 754.
• Valori float speciali: Vedi Tipi in virgola mobile per la rappresentazione API di Query dei valori speciali IEEE 754.

Sintassi del tipo:

FLOAT [ NOT NULL ]
DOUBLE [ NOT NULL ]
FLOAT64 [ NOT NULL ]

DOUBLE, FLOATe FLOAT64 specificano tutti lo stesso tipo.

Tipi di valore temporale

Valori datetime con zone

Un valore datetime con zona rappresenta un valore datetime compatibile con ISO 8601 con un offset di fuso orario.

Funzionamento del confronto:

Il sistema confronta i valori datetime con zone in ordine cronologico in base ai relativi punti di tempo assoluti.

Come scrivere valori letterali datetime:

Usare il formato ISO 8601 con le informazioni sul fuso orario.

ZONED_DATETIME('2024-08-15T14:30:00+02:00')
ZONED_DATETIME('2024-08-15T12:30:00Z')
ZONED_DATETIME('2024-12-31T23:59:59.999-08:00')

Sintassi del tipo:

ZONED DATETIME [ NOT NULL ]

Valori di durata

Un valore di durata rappresenta un intervallo diurno ISO 8601. Creane una passando una stringa di durata ISO 8601 a DURATION:

DURATION('P1DT2H30M')

I valori di durata supportano confronto, addizione, sottrazione e scala. Puoi anche aggiungere o sottrarre una durata da un data-ora zonato, oppure sottrarre due datetime zonati per ottenere una durata.

Sintassi del tipo:

DURATION [ NOT NULL ]

Tipi valore di riferimento

I valori di riferimento contengono riferimenti a nodi o archi corrispondenti.

Valori di riferimento del nodo

I valori di riferimento del nodo rappresentano riferimenti a nodi specifici nel grafico. Questi valori vengono in genere visualizzati quando i nodi vengono confrontati nei modelli a grafo. È possibile usare questi valori per accedere alle proprietà del nodo ed eseguire confronti.

Funzionamento del confronto:

Confrontare i valori di riferimento dei nodi solo per verificarne l'uguaglianza. Due valori di riferimento del nodo sono uguali se e solo se fanno riferimento allo stesso nodo.

Graph definisce un ordine deterministico rispetto ai valori di riferimento. Tuttavia, questo ordine può passare dalla query alla query e non è consigliabile basarsi su di esso nelle query di produzione.

Come accedere alle proprietà:

Usare la notazione dot per accedere alle proprietà del nodo:

node_var.property_name

Tipi di nodo astratti negli schemi del grafo:

Quando si utilizzano tipi di grafo, definire tipi di nodo astratti che fungono da tipi di base per l'ereditarietà, ma non possono essere create direttamente istanze. I tipi astratti consentono modelli di query polimorfiche:

-- Abstract base type (cannot be instantiated)
ABSTRACT
(:Person => {
  id :: INT64,
  name :: STRING,
  birth_date :: ZONED DATETIME
}),

-- Concrete types that inherit from abstract base
(:Employee => Person {
  employee_id :: STRING,
  department :: STRING,
  hire_date :: ZONED DATETIME
})

(:Customer => :Person {
  customer_id :: STRING,
  membership_level :: STRING,
  registration_date :: ZONED DATETIME
})

Query polimorfiche con tipi astratti:

I tipi astratti consentono modelli avanzati di query in cui si trova la corrispondenza con il tipo di base per trovare tutte le istanze dei tipi derivati:

-- Find all Person instances (both Employee and Customer)
MATCH (p:Person)
RETURN p.name, p.birthday, labels(p) AS label_names

-- Mixed type patterns
MATCH (e:Employee)-[:knows]-(c:Customer)
WHERE e.department = 'Sales' AND c.membership_level = 'Premium'
RETURN e.name AS sales_person, c.name AS customer

Questo approccio offre sicurezza dei tipi, abilitando la modellazione dei dati flessibile basata sull'ereditarietà negli schemi del grafo.

Sintassi del tipo:

NODE [ NOT NULL ]

Valori di riferimento dei bordi del grafo

I valori di riferimento dei bordi del grafo rappresentano riferimenti a bordi specifici nel grafico. Questi valori vengono in genere visualizzati quando i bordi vengono confrontati nei modelli a grafo. È possibile usare questi valori per accedere alle proprietà perimetrali ed eseguire confronti.

Funzionamento del confronto:

È possibile confrontare solo i valori dei riferimenti ai bordi per verificarne l'uguaglianza. Due valori di riferimento ai bordi sono uguali solo se fanno riferimento allo stesso bordo.

Come accedere alle proprietà:

Usare la notazione con punti per accedere alle proprietà perimetrali:

edge_var.property_name

Sintassi del tipo:

EDGE [ NOT NULL ]

Tipi di valore irrilevante

I tipi di valore irrilevante non contengono valori materiali "ordinari".

Valori nulli

Il valore Null rappresenta l'assenza di un valore materiale noto. È un membro di ogni tipo valore nullable ed è distinto da qualsiasi valore materiale. È l'unico valore del tipo Null.

Funzionamento del confronto:

Quando si confronta un valore con null, il risultato è UNKNOWN.

Come scrivere valori letterali Null:

NULL        -- type NULL
UNKNOWN     -- type BOOL

Sintassi del tipo:

NULL

Nessun tipo

Il tipo nothing è un tipo valore che non contiene valori.

Anche se potrebbe sembrare una tecnica, il tipo nothing consente di assegnare un tipo preciso a valori come valori di elenco vuoti. Il tipo nothing consente di passare elenchi vuoti ovunque sia previsto un tipo di valore elenco (indipendentemente dal tipo di elemento elenco richiesto).

Sintassi del tipo:

NOTHING
NULL NOT NULL

(NOTHING e NULL NOT NULL specificare lo stesso tipo)

Tipi valore costruiti

Elencare i valori

I valori di elenco sono sequenze di elementi. Gli elenchi possono contenere elementi dello stesso tipo e possono includere valori Null.

Funzionamento del confronto:

Gli elenchi vengono confrontati prima per dimensione, quindi elemento per elemento nell'ordine. Due elenchi sono uguali se hanno le stesse dimensioni e tutti gli elementi corrispondenti sono uguali.

Elenchi di gruppi:

Gli elenchi di gruppi sono elenchi associati dai modelli di arco a lunghezza variabile corrispondenti. Il grafico tiene traccia dello stato come elenchi di gruppi.

È possibile usare gli elenchi di gruppi nell'aggregazione orizzontale. Per altre informazioni, vedere Espressioni e funzioni GQL.

Come scrivere valori letterali elenco:

Usare la notazione tra parentesi quadre per creare elenchi:

[1, 2, 3, 4]
['hello', 'world']
[1.20m, 3.45m, NULL]
[]  -- empty list

Come accedere agli elementi:

Usare parentesi quadre con indicizzazione in base zero per accedere agli elementi dell'elenco:

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

Operazioni di elenco comuni:

-- Check if list contains a value
WHERE 'Engineering' IN employee.departments

-- List concatenation
RETURN [1, 2] || [3, 4]  -- [1, 2, 3, 4]

-- List size
size(list_var)

-- Test elements against a predicate
ANY(element IN list_var WHERE element IS NOT NULL)

Usa le ALLfunzioni predicate , ANY, NONE, e SINGLE list per testare quanti elementi di lista soddisfano una condizione.

Sintassi del tipo:

LIST<element_type> [ NOT NULL ]
LIST<element_type NOT NULL> [ NOT NULL ]

Dove element_type può essere qualsiasi tipo supportato, ad esempio STRING, INT64, DOUBLE, BOOL e altro ancora.

Valori di percorso

I valori di percorso rappresentano i percorsi corrispondenti nel grafico. Un valore di percorso contiene una sequenza nonempty di valori di riferimento di nodi e bordi alternati che iniziano sempre e terminano con un valore di riferimento del nodo. Questi valori di riferimento identificano i nodi e i bordi del percorso originariamente corrispondente nel grafico.

Modalità di struttura dei percorsi:

Un percorso è costituito da:

• Sequenza di nodi e archi: node₁ - edge₁ - node₂ - edge₂ - ... - nodeₙ
• Inizia sempre e termina con un nodo.
• Contiene almeno un nodo (la lunghezza minima del percorso è zero bordi).

Funzionamento del confronto:

Puoi confrontare i valori dei percorsi per l'uguaglianza e usarli come chiavi di ordinamento. Due valori di percorso sono uguali quando contengono la stessa sequenza di riferimenti tra nodo e spigolo. Non affidarti all'ordine relativo di ordinamento dei diversi percorsi tra le query.

Sintassi del tipo:

PATH [ NOT NULL ]

Conversioni e cast dei tipi

GQL supporta conversioni di tipi implicite ed esplicite per abilitare operazioni flessibili mantenendo al contempo la sicurezza dei tipi.

Conversioni implicite

Alcuni tipi di valori numerici possono essere convertiti implicitamente quando un'espressione richiede un tipo comune:

• Intero e virgola mobile: L'intero viene convertito in un tipo numerico approssimativo.

Cast esplicito

Usare la CAST funzione per convertire in modo esplicito i valori tra tipi compatibili:

CAST(value AS target_type)

Esempi:

CAST(123 AS STRING)           -- "123"
CAST('456' AS INT64)          -- 456
CAST(3.14 AS STRING)          -- "3.14"
CAST('true' AS BOOL)          -- TRUE
CAST(-42.9m AS INT64)         -- -42
CAST(1.20m AS STRING)         -- "1.20"

Regole di cast:

• A STRING: è possibile eseguire il cast della maggior parte dei tipi di valore in STRING usando la relativa rappresentazione letterale.
• A BOOL: è possibile eseguire il cast di stringhe 'true' o 'false' (senza distinzione tra maiuscole e minuscole) ai valori booleani.
• Cast non validi: se si tenta di eseguire il cast di valori incompatibili, si verificano errori di runtime.

Contenuti correlati

• Guida al linguaggio GQL
• Espressioni e funzioni GQL
• Tipi di grafo GQL
• Codifica dei valori dell'API per query GQL