Valori e tipi valore 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.

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.

Importante

Questo articolo utilizza esclusivamente il dataset di esempio dei grafi dei social network.

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.

Annotazioni

Tutti i tipi valore sono nullable per impostazione predefinita, a meno che non siano dichiarati in modo esplicito come NOT NULL. Ad esempio, INT specifica il tipo integer nullable, mentre INT NOT NULL specifica il tipo integer materiale.

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 (elenchi, 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.
• Tutti i numeri possono essere confrontati tra loro (ad esempio, numeri interi con valori float).
• È possibile confrontare solo i valori di riferimento che fanno riferimento allo stesso tipo di oggetto (riferimenti a nodi con riferimenti a nodi, riferimenti ai bordi 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. Tuttavia, l'istruzione considera ORDER BY come il valore più piccolo durante l'ordinamentoNULL, fornendo un comportamento di ordinamento prevedibile.

Distinzione vs. uguaglianza

Alcune istruzioni non testano l'uguaglianza, ma piuttosto per la diseguaglianza. 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 .

Il test di distinctness viene usato da:

• 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 vengono considerate distinte se è presente almeno una colonna in cui i valori di entrambe le righe sono distinti.

Tipi valore booleani

I valori booleani sono i valori logici a tre valori TRUE, FALSEe UNKNOWN.

Annotazioni

UNKNOWN e il valore Null sono identici. UNKNOWN è solo un valore Null di tipo BOOL.

Funzionamento dell'uguaglianza:

Valore sinistro	Valore destro	Result
TRUE	FALSE	FALSE
TRUE	TRUE	TRUE
TRUE	SCONOSCIUTO	SCONOSCIUTO
FALSE	FALSE	TRUE
FALSE	TRUE	FALSE
FALSE	SCONOSCIUTO	SCONOSCIUTO
SCONOSCIUTO	FALSE	SCONOSCIUTO
SCONOSCIUTO	TRUE	SCONOSCIUTO
SCONOSCIUTO	SCONOSCIUTO	SCONOSCIUTO

Funzionamento del confronto:

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

Come scrivere valori letterali booleani:

• TRUE
• FALSE
• UNKNOWN o 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 (il metodo di confronto è talvolta denominato UCS_BASIC regole 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:

Input	Carattere senza caratteri di escape
\\	\
\"	"
\'	'
\`	`
\t	U + 0009
\b	U + 0008
\n	U+000A
\r	U + 000D
\f	U + 000C
\uabcd	U+ABCD
\UABCDEF01	U+ABCDEF01

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

Stringa effettiva	Stile C	Stile SQL
Come "Ironic!"	"How \"ironic!\""	"How ""ironic!"""
Come 'ironico!'	'How \'ironic!\''	'How ''ironic!'''

Suggerimento

Disabilitare gli escape in stile \C anteponendo al valore letterale stringa .@

Sintassi del tipo:

STRING [ NOT NULL ]

Tipi numerici

Tipi numerici esatti

Graph in Microsoft Fabric supporta numeri esatti che sono numeri interi negativi o positivi.

Funzionamento del confronto:

Il sistema confronta tutti i numeri in base al relativo valore numerico.

Come scrivere valori letterali integer:

Description	Example	Value
Integer	123456	123456
Raggruppamento intero w.	123_456	123456
Intero positivo in modo esplicito	+123456	123456
Zero	0	0
Intero negativo	-123456	-123456

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 in Microsoft Fabric 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 tutti i numeri in base al relativo valore numerico.

Come scrivere valori letterali a virgola mobile:

Description	Example	Value
Notazione comune	123.456	123.456
Notazione comune w. raggruppamento	123_456.789	123456.789
Notazione scientifica	1.23456e2	123.456
Notazione scientifica (maiuscola)	1.23456E2	123.456
A virgola mobile con suffisso	123.456f	123.456
Precisione doppia con suffisso	123.456d	123.456

Considerazioni numeriche aggiuntive:

• Overflow e underflow: le operazioni integer che superano l'intervallo supportato possono causare errori di runtime o comportamento di ritorno a capo a seconda dell'implementazione.
• Precisione: le operazioni a virgola mobile possono perdere precisione a causa di limitazioni della rappresentazione IEEE 754.
• Valori float speciali: NaN (Non un numero), infinito positivo (+∞) e infinito negativo (-∞) possono essere supportati nei contesti a virgola mobile.

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 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 ]

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 ed è possibile usarli per accedere alle proprietà dei nodi ed eseguire confronti.

Funzionamento del confronto:

È consigliabile confrontare solo i valori di riferimento del nodo per verificarne l'uguaglianza. Due valori di riferimento del nodo sono uguali se e solo se fanno riferimento allo stesso nodo.

Graph in Microsoft Fabric definisce un ordine deterministico rispetto ai valori di riferimento. Tuttavia, questo ordine può passare dalla query alla query e non deve essere basato sulle 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 lavora con i tipi di grafo, è possibile definire tipi di nodo astratti che fungono da tipi di base per l'ereditarietà, ma non è possibile creare direttamente un'istanza. 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 è possibile trovare le corrispondenze 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

Annotazioni

Le query precedenti assumono il tipo di grafico descritto sopra e non utilizzano il set di dati di esempio del social network.

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 ed è possibile usarli per accedere alle proprietà dei bordi 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 se e 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.

Importante

Attualmente, gli elenchi nel grafico in Microsoft Fabric non possono contenere elementi di tipi misti.

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.

Suggerimento

I confronti che coinvolgono valori di elemento Null comportano UNKNOWNsempre . I confronti Null possono portare a risultati sorprendenti durante il confronto dei valori di elenco.

Elenchi di gruppi:

Gli elenchi di gruppi sono elenchi associati dai modelli di arco a lunghezza variabile corrispondenti. Graph in Microsoft Fabric tiene traccia dello stato come elenchi di gruppi.

Gli elenchi di gruppi possono essere usati 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, 'mixed', TRUE, 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)

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 così via.

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).

Annotazioni

Attualmente la sintassi letterale per i percorsi non è ancora supportata. I percorsi possono invece essere associati usando MATCH pathVar=...path pattern....

Funzionamento del confronto:

I percorsi vengono confrontati confrontando liste di valori di riferimento con tutti i loro nodi e archi costituenti, nella sequenza in cui si verificano lungo il percorso.

Consulta le regole di confronto per i valori di lista e di riferimento per ulteriori dettagli.

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 valore possono essere convertiti in modo implicito quando la conversione è sicura e non perde informazioni:

• Estensione numerica: i valori integer possono essere convertiti in modo implicito in tipi a virgola mobile quando vengono usati nelle operazioni aritmetiche miste.
• Contesti stringa: i valori possono essere convertiti in modo implicito in stringhe in determinati contesti, ad esempio le operazioni di concatenazione.

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

Regole di cast:

• Per STRING: è possibile eseguire il cast della maggior parte dei tipi di valore in STRING con la relativa rappresentazione letterale.
• Per i tipi numerici: è possibile eseguire il cast di stringhe contenenti valori letterali numerici validi ai tipi numerici appropriati.
• Per BOOL: è possibile eseguire il cast di stringhe 'true'/'false' (senza distinzione tra maiuscole e minuscole) ai valori booleani.
• Cast non validi: il tentativo di eseguire il cast di valori incompatibili genera errori di runtime.

Contenuti correlati

• Guida al linguaggio GQL
• Espressioni e funzioni GQL
• Tipi di grafo GQL
• Provare Gratuitamente Microsoft Fabric