Référence rapide GQL

Cet article est une référence rapide pour la syntaxe GQL (Graph Query Language) pour graph dans Microsoft Fabric. Utilisez-le pour rappeler la syntaxe et les défauts. Pour une explication de bout en bout, voir le guide du langage GQL ; chaque section renvoie à la référence ciblée qui détient tous les détails.

Note

Cet article utilise principalement l’exemple de jeu de données de graphique de réseau social. Il fournit également quelques exemples qui utilisent le jeu de données Adventure Works à partir du didacticiel de graphe.

Structure de la requête

Les requêtes GQL utilisent une séquence d’instructions qui définissent les données à obtenir à partir du graphique, comment les traiter et comment afficher les résultats. Chaque instruction a un objectif spécifique et, ensemble, ils créent un pipeline linéaire qui correspond aux données du graphique et les transforme pas à pas.

Flux de requête classique :
Une requête GQL commence généralement en spécifiant le modèle de graphique à mettre en correspondance. Ensuite, elle utilise des instructions facultatives pour la création de variables, le filtrage, le tri, la pagination et la sortie du résultat.

Exemple :

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

Composition de l’énoncé :

Important

Les instructions forment un pipeline ordonné et ne peuvent pas être réarrangées arbitrairement. Consultez l’article sur les limitations actuelles.

  • MATCH : spécifiez des modèles de graphique à rechercher.
  • LET : définissez des variables à partir d’expressions.
  • FOR – Développer une liste en lignes.
  • CALL – Exécuter une sous-requête en ligne et ajouter ses colonnes retournées.
  • FILTER : conservez les conditions de correspondance des lignes.
  • WHEN – Acheminer chaque ligne d’entrée vers la première branche conditionnelle correspondante.
  • ORDER BY - Trier les résultats.
  • OFFSET : ignorez de nombreuses lignes.
  • LIMIT : limitez le nombre de lignes.
  • RETURN – Sortie des résultats finaux.
  • NEXT – Commencer une autre étape de requête en utilisant les colonnes retournées par l’étape précédente.

Chaque instruction s’appuie sur la précédente, afin d’affiner et de mettre en forme de manière incrémentielle la sortie de la requête. Utilisez UNION, UNION DISTINCT, ou UNION ALL pour combiner des blocs de requête complets. Pour plus d’informations sur chaque instruction, consultez les sections suivantes.

Instructions de requête SQL

MATCH

Recherchez des modèles de graphiques dans vos données.

Syntaxe :

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

Exemple :

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

Pour plus d’informations sur l’instruction MATCH , consultez les modèles Graph.

LAISSER

Créez des variables à l’aide d’expressions.

Syntaxe :

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

Exemple :

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

Pour plus d’informations sur l’instruction LET , consultez le guide de langue GQL.

FOR

Développe une liste en lignes et retourne optionnellement la position de chaque élément.

Syntaxe :

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

Exemple :

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

WITH OFFSET commence à 0. WITH ORDINALITY commence à 1.

Pour plus d’informations sur l’instruction FOR , consultez le guide de langue GQL.

CALL

Exécute une sous-requête en ligne pour chaque ligne d’entrée. Les variables déjà dans le champ d’application sont implicitement disponibles à l’intérieur de la sous-requête.

Syntaxe :

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

Parmi les variables créées à l’intérieur de la sous-requête, seules les colonnes de sa déclaration finale RETURN deviennent disponibles en dehors de celle-ci. Ordinary CALL supprime une ligne extérieure lorsque la sous-requête ne renvoie aucune ligne et la multiplie lorsque la sous-requête renvoie plusieurs lignes. OPTIONAL CALL préserve une ligne externe avec NULL des colonnes de sous-requête lorsque la sous-requête ne retourne aucune ligne.

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

Pour plus d’informations sur les sous-requêtes en ligne, consultez le guide du langage GQL.

FILTRE

Conserve les lignes qui correspondent aux conditions.

Syntaxe :

FILTER [ WHERE ] <predicate>
...

Exemple :

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

Pour plus d’informations sur l’instruction FILTER , consultez le guide de langue GQL.

ORDONNER PAR

Trie les résultats.

Syntaxe :

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

Exemple :

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

Le placement nul est indépendant de la direction de tri. Le défaut est NULLS LAST pour les deux ASC et DESC; spécifier NULLS FIRST de placer les valeurs nulles avant les valeurs non nulles.

Important

L’ordre demandé des lignes n’est garanti de tenir qu’immédiatement après une instruction précédente ORDER BY . Les instructions suivantes (le cas échéant) ne sont pas garanties de conserver un tel ordre.

Pour plus d’informations sur l’instruction ORDER BY , consultez le guide de langue GQL.

OFFSET/LIMIT

Ignorez les lignes et limitez le nombre de résultats.

Syntaxe :

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

Exemple :

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

Pour plus d’informations sur les instructions et OFFSET les LIMIT instructions, consultez le guide de langue GQL.

RETURN

Affichez les résultats finaux.

Syntaxe :

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

Exemple :

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

Pour plus d’informations sur l’instruction RETURN , consultez le guide de langue GQL.

NEXT

Une nouvelle étape de requête commence le début. Seules les colonnes retournées par l’étape précédente sont disponibles après NEXT.

Syntaxe :

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

Exemple :

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Chaque étape peut contenir une union de blocs de requête. L’union est évaluée à l’intérieur de cette étape avant que sa sortie ne franchisse la NEXT frontière.

Pour plus d’informations sur NEXT, consultez le guide linguistique GQL.

Instructions conditionnelles

Aroute chaque ligne d’entrée vers la première WHEN branche dont le prédicat évalue à TRUE.

Syntaxe :

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

Les prédicats doivent être booléens et sont évalués dans l’ordre. FALSE et UNKNOWN tomber à travers la branche suivante. Si aucune branche ne correspond et qu’il n’y a pas ELSE, la ligne d’entrée est omise. Les prédicats après la première correspondance et les branches non sélectionnées ne sont pas évalués.

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

Toutes les branches doivent retourner les mêmes noms de colonnes avec des types de données compatibles. Enfermez une branche en entrethèses lorsqu’elle contient une procédure imbriquée.

Pour plus d’informations, voir Énoncés conditionnels.

UNION

Combine la sortie des blocs de requête complets.

Syntaxe :

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

Mettre UNION à nu et UNION DISTINCT supprimer les lignes dupliquées. UNION ALL préserve les lignes en double. Chaque bloc de requête doit retourner le même ensemble de noms de colonnes avec des types de données compatibles.

Pour plus d’informations sur les syndicats, consultez le guide linguistique du GQL.

Modèles graphiques

Les modèles de graphique décrivent la structure du graphique à mettre en correspondance.

Modèles de nœud

Dans les bases de données de graphiques, utilisez des nœuds pour représenter des entités, telles que des personnes, des produits ou des emplacements.

Les modèles de nœud décrivent comment faire correspondre les nœuds dans le graphique. Vous pouvez filtrer par étiquette ou lier des variables.

(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

Pour plus d’informations sur les modèles de nœud, consultez les modèles Graph.

Modèles de périphérie

Les modèles de périphérie spécifient des relations entre les nœuds, y compris le sens et le type de périphérie. Dans les bases de données de graphiques, un bord représente une connexion ou une relation entre deux nœuds.

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

Pour plus d’informations sur les modèles de périphérie, consultez les modèles Graph.

Expressions d’étiquette

Les expressions d’étiquette vous permettent de faire correspondre des nœuds avec des combinaisons d’étiquettes spécifiques à l’aide d’opérateurs logiques.

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

Pour plus d’informations sur les expressions d’étiquette, consultez les modèles Graph.

Modèles de chemin d’accès

Les modèles de chemin décrivent les traversées par le graphique, y compris les nombres de tronçons et les liaisons de variables.

(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 est le mode chemin par défaut et permet la répétition des nœuds et des arêtes. TRAIL Empêche les arêtes répétées. SIMPLE empêche les nœuds répétés sauf lors d’un cycle de fermeture de l’avant-dernier, et ACYCLIC empêche tous les nœuds répétés. Les deux modes uniques à chaque nœud empêchent également la répétition des arêtes, car la réutilisation des arêtes répéterait les nœuds d’extrémité. ALL est la recherche de chemin par défaut. ANY SHORTEST renvoie un chemin le plus court pour chaque paire source-destination et ne choisit pas de manière déterministe parmi les chemins liés.

Les quantificateurs supportés incluent fixes {n}, bornées {m,n} et {,n}, et non bornées {m,}, *, et +. Les motifs non bornés ALL WALK ne sont pas pris en charge ; utilisez un mode chemin de terminaison. Non borné ANY SHORTEST WALK comporte des restrictions supplémentaires de forme et de valeur de trajectoire. Pour plus de détails, voir les motifs de graphes GQL.

Pour plus d’informations sur les modèles de chemin d’accès, consultez les modèles Graph.

Modèles multiples

Utilisez plusieurs modèles pour faire correspondre des structures de graphe complexes et non linéaires dans une seule requête.

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

Pour plus d’informations sur plusieurs modèles, consultez les modèles Graph.

Valeurs et types de valeurs

Types de base

Les types de base sont des valeurs de données primitives telles que des chaînes, des nombres, des booléens et des datetimes.

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

Le suffixe d or D crée un littéral approximatif FLOAT64 . Un exposant sans suffixe crée également une FLOAT64 valeur. Les f suffixes et F littéraux ne sont pas actuellement pris en charge.

Pour plus d’informations sur les types de base, consultez les valeurs GQL et les types valeur.

Types de valeurs de référence

Les types de valeurs de référence sont des nœuds et des arêtes que vous utilisez comme valeurs dans les requêtes.

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

Pour plus d’informations sur les types de valeurs de référence, consultez valeurs GQL et types valeur.

Types de collection

Les types de collection regroupent plusieurs valeurs, telles que des listes et des chemins d’accès.

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

Pour plus d’informations sur les types de collection, consultez les valeurs GQL et les types valeur.

Types matériels et nullables

Chaque type de valeur est nullable (inclut la valeur null) ou le matériau (exclut). Par défaut, les types sont nullables, sauf si vous spécifiez NOT NULLexplicitement .

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

Expressions &opérateurs

Conditional

Les expressions simples CASE comparent une expression avec une ou plusieurs valeurs.

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

Les expressions recherchées CASE WHEN <predicate> ne sont pas prises en charge. Utilisez une instruction conditionnelle pour router les lignes selon les prédicats.

Pour plus d’informations sur les expressions conditionnelles, consultez les fonctions et expressions GQL.

Comparison

Les opérateurs de comparaison comparent les valeurs et vérifient l’égalité, l’ordre ou les valeurs Null.

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

Pour plus d’informations sur les prédicats de comparaison, consultez les expressions et fonctions GQL.

Logical

Les opérateurs logiques combinent ou annulent des conditions booléennes dans les requêtes.

AND, OR, NOT, XOR               -- Boolean logic

Pour plus d’informations sur les expressions logiques, consultez les expressions et fonctions GQL.

EXISTS

Teste si une sous-requête procédure-formulaire renvoie au moins une ligne.

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

EXISTS renvoie une valeur booléenne non nulle. Utilisez NOT EXISTS pour tester que la sous-requête ne renvoie aucune ligne. Vous pouvez utiliser le résultat dans WHERE ou FILTER, LET, RETURN, ORDER BY, et le filtre ou les expressions source agrégées. EXISTS n’est pas prise en charge dans un filtre de prédicat de liste.

Important

Les formes uniquement à motifs graphiques comme EXISTS { (p)-[:knows]->(friend) } et EXISTS ((p)-[:knows]->(friend)) ne sont pas prises en charge. Utilisez le formulaire de procédure avec MATCH montré dans l’exemple précédent.

Avertissement

Un agrégat non groupé comme , RETURN count(*) retourne une ligne même lorsqu’aucun motif ne correspond. Parce que EXISTS teste les lignes, cette forme évalue à TRUE.

Pour plus d’informations sur EXISTS, voir Sous-requêtes d’existence.

Arithmetic

Les opérateurs arithmétiques effectuent des calculs sur des nombres.

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

Pour plus d’informations sur les expressions arithmétiques, consultez les expressions et fonctions GQL.

Modèles de chaîne

Les prédicats de modèle de chaîne correspondent à des sous-chaînes, des préfixes ou des suffixes dans des chaînes.

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

Pour plus d’informations sur les prédicats de modèle de chaîne, consultez les expressions et fonctions GQL.

Répertorier les opérations

Répertorier l’appartenance aux opérations de test, les éléments d’accès et la longueur de la liste de mesures.

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

Listez les fonctions prédicatives retournent TRUE, FALSE, ou UNKNOWN selon les résultats du filtre. Pour une liste vide, ALL et NONE retourner TRUE, tandis que ANY et SINGLE retourner FALSE. Une liste de sources nulles renvoie UNKNOWN.

La liaison des éléments est locale au filtre et peut ombrer une variable extérieure. Les agrégats sur cette liaison locale et EXISTS les sous-requêtes à l’intérieur du filtre ne sont pas pris en charge.

Pour plus d’informations, voir Lister les fonctions prédicatives.

Accès à la propriété

L’accès aux propriétés obtient la valeur d’une propriété à partir d’un nœud ou d’un bord.

n.firstName                      -- Property access

Pour plus d’informations sur l’accès aux propriétés, consultez les expressions et fonctions GQL.

Functions

Utilisez des fonctions intégrées pour transformer des valeurs, inspecter les éléments du graphe et agréger les lignes.

Fonctions numériques

Les fonctions numériques calculent des valeurs numériques ou produisent des plages d’entiers.

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

D’autres fonctions trigonométriques prises en charge sont TAN, COT, ATAN, SINH, COSH, et TANH. Sauf pour ABS et RANGE, ces fonctions numériques retournent DOUBLE.

En savoir plus sur les fonctions numériques dans les expressions et fonctions GQL.

Fonctions d'agrégation

Les fonctions d’agrégation calculent des valeurs récapitulatives pour les groupes de lignes (agrégation verticale) ou sur les éléments d’une liste de groupes (agrégation horizontale).

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

Sans regrouper les colonnes, une requête agrégée sans lignes d’entrée retourne pour , une liste vide pour COLLECT_LIST et COLLECT_ELEMENTS, et nulle pour SUM, AVG, MIN, MAX, et COLLECT_ONE.COUNT0 Un argument de liste de groupes rend l’agrégat horizontal.

En savoir plus sur les fonctions d’agrégation dans les expressions et fonctions GQL.

Fonctions de chaîne

Les fonctions de chaîne vous permettent d’utiliser et d’analyser les valeurs de chaîne.

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

Les motifs Regex, les remplacements et les options doivent être des lettres littérales. Pour les signatures, les drapeaux et le comportement nul, voir Fonctions de chaîne.

Fonctions de liste

Les fonctions de liste vous permettent d’utiliser des listes, telles que la vérification de la longueur ou de la taille de découpage.

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

Pour plus d’informations sur les fonctions de liste, consultez les expressions et fonctions GQL.

Fonctions graphiques

Les fonctions graphes vous permettent d’obtenir des informations à partir de nœuds, de chemins et de bords.

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

Pour plus d’informations sur les fonctions de graphe, consultez les expressions et fonctions GQL.

Fonctions temporelles

Les fonctions temporelles vous permettent d’utiliser des valeurs de date et d’heure.

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

Pour plus d’informations sur les fonctions temporelles, consultez les expressions et fonctions GQL.

Fonctions génériques

Les fonctions génériques vous permettent d’utiliser des données de manière courante.

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

Pour plus d’informations sur les fonctions génériques, consultez les expressions et fonctions GQL.

Exemples orientés tâche

Utilisez les articles pratiques lorsque vous avez besoin de schémas de requête complets et prêts à être adaptés :

Contenu connexe

  • Last updated on