Expressions, prédicats et fonctions GQL

Cet article fournit une référence complète pour les expressions GQL, les prédicats et les fonctions intégrées disponibles dans les requêtes Microsoft Fabric. Utilisez cette référence pour comprendre comment effectuer des calculs, filtrer les résultats et transformer des données dans vos requêtes de graphe.

Pour obtenir une vue d’ensemble du langage de requête GQL et des exemples de requêtes de bout en bout, consultez le guide de langage GQL. Pour plus d’informations sur les types de données pris en charge et la syntaxe littérale, consultez les valeurs GQL et les types valeur.

Littéraux

Les littéraux sont des expressions simples qui évaluent directement la valeur indiquée. L’article sur les valeurs et les types de valeurs GQL décrit en détail les littéraux de chaque type de valeur.

Exemple :

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

Pour obtenir une syntaxe littérale détaillée pour chaque type de données, consultez les valeurs GQL et les types valeur.

Predicates

Les prédicats sont des expressions booléennes que vous utilisez couramment pour filtrer les résultats dans les requêtes GQL. Ils sont évalués à TRUE, FALSEou UNKNOWN (null).

Caution

Lorsque vous utilisez des prédicats comme filtre, ils conservent uniquement les éléments pour lesquels le prédicat est TRUEévalué .

Prédicats de comparaison

Utilisez ces opérateurs pour comparer les valeurs :

= (égal)
<> (non égal)
< (inférieur à)
> (supérieur à)
<= (inférieur ou égal)
>= (supérieur ou égal)

GQL utilise une logique à trois valeurs où les comparaisons avec retour UNKNOWNnull :

Expression	Résultat
`5 = 5`	`TRUE`
`5 = 3`	`FALSE`
`5 = NULL`	`UNKNOWN`
`NULL = NULL`	`UNKNOWN`

Pour un comportement de comparaison spécifique, consultez la documentation de chaque type valeur dans les valeurs GQL et les types valeur.

Exemple :

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

Si les deux opérandes sont des nombres, GQL les compare par leurs valeurs numériques.

Important

Graph ne prend pas encore en charge toutes les comparaisons numériques définies par GQL. Le comportement actuel utilise ces règles :

Une comparaison entre un entier et un nombre approximatif convertit l’entier en un type numérique approximatif.
Une comparaison entre les valeurs entières signées et non signées convertit généralement les deux valeurs en un type entier signé. Une valeur non signée en dehors de la plage d’entiers signés provoque une erreur.

Expression logiques

Combinez des conditions avec des opérateurs logiques :

AND (les deux conditions true)
OR (l’une ou l’autre condition true)
NOT (condition de négation)
XOR (disjonction exclusive - true quand exactement un opérande est vrai)

Exemple :

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

Prédicats d’existence de propriété

Pour vérifier si des propriétés existent, utilisez ces prédicats :

p.locationIP IS NOT NULL
p.browserUsed IS NULL

Note

Tenter d’accéder à une propriété connue comme inexistante entraîne une erreur de syntaxe. L’accès à une propriété potentiellement inexistante s’évalue à null. La détermination de savoir si une propriété est connue ou potentiellement non existante est basée sur le type du nœud ou du bord accédé.

Sous-requêtes d’existence

Utilisez une sous-requête procédura-forme EXISTS pour tester si une requête imbriquée retourne au moins une ligne :

EXISTS {
  <query statements>
  RETURN <columns>
}

Le résultat est une valeur booléenne non nulle :

TRUE si la sous-requête renvoie une ou plusieurs lignes.
FALSE si la sous-requête ne retourne aucune ligne.

Les variables déjà dans le champ d’application sont implicitement disponibles à l’intérieur de la sous-requête. Les variables introduites uniquement à l’intérieur de la sous-requête ne sont pas disponibles en dehors de celle-ci.

Utilisation EXISTS dans un filtre :

MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}
RETURN p.firstName, p.lastName

Utiliser NOT EXISTS pour conserver des lignes pour lesquelles la sous-requête ne retourne aucune ligne. Vous pouvez aussi utiliser EXISTS dans LET, RETURN, ORDER BY, et agréger des expressions filtres ou sources. 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 montré dans les exemples précédents. Les sous-requêtes scalaires VALUE { ... } ne sont pas prises en charge.

Caution

EXISTS teste si la sous-requête renvoie une ligne, et non si une valeur globale est non nulle. Un agrégat non groupé tel que RETURN count(*) renvoyez une ligne même lorsque MATCH ne trouve aucune ligne, de sorte que cette forme de EXISTS évalue à TRUE. Retournez une variable appariée lorsque vous voulez tester l’existence de correspondances.

Pour plus d’informations sur les sous-requêtes corrélées, voir l’instructionCALL dans le guide du langage GQL.

Répertorier les prédicats d’appartenance

Testez si les valeurs se trouvent dans des listes :

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

Fonctions prédicatives à liste

Utilisez une fonction de prédicat de liste pour évaluer une expression booléenne pour les éléments d’une liste :

ALL(element IN list WHERE predicate)
ANY(element IN list WHERE predicate)
NONE(element IN list WHERE predicate)
SINGLE(element IN list WHERE predicate)

La source peut être un littéral de liste, une propriété à valeur de liste, une variable ou une liste de groupe issue d’un motif de longueur variable.

Les fonctions ont les significations suivantes :

Function	Sens
`ALL`	Chaque élément satisfait le prédicat.
`ANY`	Au moins un élément satisfait le prédicat.
`NONE`	Aucun élément ne satisfait le prédicat.
`SINGLE`	Exactement un élément satisfait le prédicat.

L’exemple suivant évalue les quatre fonctions sur une liste construite dynamiquement :

LET items = [1, 2, 3]
RETURN ALL(x IN items WHERE x > 0) AS all_match,
       ANY(x IN items WHERE x = 2) AS any_match,
       NONE(x IN items WHERE x < 0) AS none_match,
       SINGLE(x IN items WHERE x = 2) AS single_match

Les quatre valeurs retournées sont TRUE.

Vous pouvez également évaluer les propriétés des éléments à partir d’une liste. Dans cet exemple, connections est la liste de groupes créée par le motif d’arêtes à longueur variable :

MATCH (person:Person)-[connections:knows]->{1,4}(friend:Person)
WHERE ALL(connection IN connections WHERE connection.creationDate IS NOT NULL)
RETURN person.firstName, friend.firstName

Les prédicats de liste utilisent une logique à trois valeurs. Le tableau décrit le résultat en termes des valeurs produites par l’expression du filtre pour les éléments de la liste :

Function	`TRUE`	`FALSE`	`UNKNOWN`	Liste vide
`ALL`	Tout résultat de filtre est `TRUE`.	Au moins un résultat est `FALSE`.	Aucun résultat n’est `FALSE`, et au moins un est `UNKNOWN`.	`TRUE`
`ANY`	Au moins un résultat de filtre est `TRUE`.	Aucun résultat n’est `TRUE` ni `UNKNOWN`.	Aucun résultat n’est `TRUE`, et au moins un est `UNKNOWN`.	`FALSE`
`NONE`	Aucun résultat n’est `TRUE` ni `UNKNOWN`.	Au moins un résultat est `TRUE`.	Aucun résultat n’est `TRUE`, et au moins un est `UNKNOWN`.	`TRUE`
`SINGLE`	Exactement un résultat est `TRUE`, et aucun n’est `UNKNOWN`.	Plus d’un résultat est `TRUE`, ou aucun résultat n’est `TRUE` ou `UNKNOWN`.	Au plus un résultat est `TRUE`, et au moins un est `UNKNOWN`.	`FALSE`

Si la liste source est nulle, chaque fonction retourne UNKNOWN. Un élément de liste nul contribue au résultat de l’évaluation du filtre avec cet élément lié à nul ; il ne rend pas automatiquement le résultat de la fonction inconnu.

La variable élément n’est disponible que dans l’expression de filtre du prédicat liste. Le filtre peut également référencer des variables issues de la requête d’enclos. Si la variable élément porte le même nom qu’une variable extérieure, la variable élément locale a la priorité. Les prédicats de liste imbriqués peuvent de la même manière ombrer une variable d’élément extérieur.

Les fonctions agrégées peuvent référencer une liste de groupes entourant, mais elles ne peuvent pas agréger la variable élémentaire liée localement. EXISTS Les sous-requêtes ne sont pas non plus prises en charge dans un filtre de prédicat de liste.

ANY(...) est une fonction prédicat liste. Ne le confondez pas avec le ANY SHORTEST préfixe de recherche de chemin ou le ANY type de valeur dynamique.

Prédicats de modèle de chaîne

Mettre en correspondance des chaînes à l’aide de techniques de correspondance de modèle :

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

Pour l’appariement des expressions régulières RE2, utilisez MSFT.REGEXP_LIKE.

Expressions arithmétiques

Utilisez des opérateurs arithmétiques standard avec des valeurs numériques :

+ (ajout)
- (soustraction)
* (multiplication)
/ (division)

Les opérateurs arithmétiques suivent des conventions mathématiques générales.

Préséance:

En règle générale, les opérateurs suivent les règles de précédence des opérateurs établies, comme * avant +. Utilisez des parenthèses pour contrôler l’ordre d’évaluation si nécessaire.

Exemple :

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

Règles de contrainte :

Utilisez les règles suivantes dans l’ordre de priorité :

Les expressions arithmétiques impliquant un type numérique approximatif rendent un type numérique approximatif.
Les expressions arithmétiques impliquant à la fois des types entiers signés et non signés rendent un type entier signé.

Accès à la propriété

Accédez aux propriétés à l’aide de la notation par points :

p.firstName
edge.creationDate

Lister l’accès

Accéder aux éléments de liste à l’aide de l’indexation de base zéro :

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

Fonctions intégrées

GQL prend en charge différentes fonctions intégrées pour le traitement et l’analyse des données.

Fonctions numériques

Utilisez des fonctions numériques pour transformer les valeurs numériques, calculer les valeurs trigonométriques et créer des plages d’entiers.

Valeur absolue et puissance

Function	Descriptif
`ABS(value)`	Rend la valeur absolue. Le résultat a le même type numérique que `value`.
`POWER(base, exponent)`	Augmente `base` et `exponent` renvoie un `DOUBLE`.

Les deux fonctions acceptent les valeurs numériques. Un argument nul produit nul. Une opération numérique invalide, comme un résultat débordant POWER , produit une erreur.

RETURN ABS(-1) AS absoluteValue, POWER(2, -2) AS reciprocalSquare

Le résultat est le suivant :

Valeur absolue	reciprocalSquare
`1`	`0.25`

Fonctions trigonométriques

Les fonctions trigonométriques acceptent une valeur numérique et retournent un DOUBLE. Un argument nul produit nul.

Function	Descriptif
`SIN(value)`, `COS(value)`, `TAN(value)`, `COT(value)`	Calculez une fonction trigonométrique. `value` est un angle en radians.
`ASIN(value)`, `ACOS(value)`, `ATAN(value)`	Calculez une fonction trigonométrique inverse. Le résultat est en radians. `ASIN`et `ACOS` nécessitent une valeur de `-1` par .`1`
`SINH(value)`, `COSH(value)`, `TANH(value)`	Calculez une fonction hyperbolique.
`DEGREES(value)`	Convertit un angle de radians en degrés.
`RADIANS(value)`	Convertit un angle des degrés en radians.

Un argument en dehors du domaine mathématique d’une fonction produit une erreur.

RETURN COS(0) AS cosine, RADIANS(180) AS angle

Le résultat est le suivant :

Cosinus	angle
`1.0`	`3.141592653589793238462643383279502884`

Plages d’entiers

RANGE(start, end) renvoie une liste d’entiers de start vers end, en utilisant un pas de 1. RANGE(start, end, step) utilise le pas non nul spécifié. start, end, et step doivent être des entiers non nuls. Zéro est valable pour start ou end; il doit seulement step être non nul.

L’étendue inclut start. Cela ne s’applique end qu’en ajoutant step des portées end exactes à plusieurs reprises. Un pas positif de start plus grand que end, ou un pas négatif de start moins de end, renvoie une liste vide. Un pas zéro produit une erreur.

RETURN RANGE(0, 10, 3) AS ascending, RANGE(5, 0, -2) AS descending

Le résultat est le suivant :

ascendant	descendant
`[0, 3, 6, 9]`	`[5, 3, 1]`

Si tous les arguments sont des entiers sans signe, RANGE renvoie un LIST<UINT64>. Sinon, il retourne a LIST<INT64> et rejette des valeurs qui ne peuvent pas être représentées en toute sécurité comme des entiers signés.

Fonctions d'agrégation

Les fonctions agrégées combinent des valeurs soit entre lignes d’entrée, soit au sein d’une liste de groupes délimitée par un motif de longueur variable.

Function	Descriptif
`COUNT(*)`	Compte les lignes d’entrée, y compris celles contenant des valeurs nulles.
`COUNT(expression)`	Compte les résultats non nuls de `expression`.
`SUM(expression)`	Retourne la somme des valeurs numériques non nulles.
`AVG(expression)`	Retourne la moyenne des valeurs numériques non nulles.
`MIN(expression)`	Retourne la valeur minimale non nulle.
`MAX(expression)`	Retourne la valeur maximale non nulle.
`COLLECT_LIST(expression)`	Retourne une liste avec un élément pour chaque entrée, incluant les éléments nuls.
`COLLECT_ONE(expression)`	Retourne une valeur d’entrée non nulle. La valeur sélectionnée n’est pas déterministe.
`COLLECT_ELEMENTS(expression)`	Concaténine les éléments des entrées à valeurs de liste en une seule liste. Les listes d’entrées nulles ne contribuent pas d’éléments, mais les éléments nuls d’une liste restent dans le résultat.

Lorsqu’une requête agrégée ne comporte pas de colonnes de regroupement et ne reçoit pas de lignes d’entrée, elle COUNT retourne 0, COLLECT_LIST et COLLECT_ELEMENTS retourne une liste vide, et que les autres fonctions agrégées retournent null. Ne vous fiez pas à l’ordre des valeurs retournées par un agrégat de collection. Avec le regroupement des colonnes, aucune ligne d’entrée ne produit aucun groupe et donc aucune ligne de résultat.

Quantificateurs d’ensembles

Utilisez ALL pour inclure des valeurs en double ou DISTINCT pour les retirer. ALL est la valeur par défaut pour les agrégats d’expressions. COUNT(*) n’accepte pas de quantificateur fixe.

MATCH (person:Person)
RETURN COUNT(person) AS personCount,
       COUNT(DISTINCT person.browserUsed) AS browserCount

Pour COLLECT_LIST, DISTINCT supprime les valeurs dupliquées et conserve au maximum un nul. Pour COLLECT_ELEMENTS, DISTINCT s’applique aux éléments après que les listes d’entrées ont été concaténées. DISTINCT cela ne rend COLLECT_ONE pas déterministe.

Filtres et limites spécifiques à l’agrégat

Ajouter FILTER (WHERE predicate) après un agrégat pour n’inclure que les valeurs pour lesquelles predicate est vrai. Les résultats de prédicats faux et inconnus sont exclus. Ce filtre n’affecte que cet agrégat, et non les lignes d’entrée disponibles pour d’autres expressions dans la même RETURN.

Ajouter LIMIT n dans le filtre agrégé pour considérer au maximum n les lignes d’entrée qualifiées. Le filtrage s’effectue avant la limite spécifique à l’agrégat et DISTINCT s’applique après la limite.

MATCH (person:Person)
RETURN COUNT(*) AS allPeople,
       COUNT(*) FILTER (WHERE person.birthday < 19900101 LIMIT 5) AS sampleBornBefore1990

Agrégation entre lignes

Un agrégat combine normalement des valeurs verticalement sur les lignes d’entrée. Utilisez GROUP BY pour calculer un résultat par groupe.

MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year

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

Ne placez pas un agrégat vertical directement dans un autre dans le même bloc de requête. Par exemple, SUM(COUNT(*)) n’est pas valide. À utiliser NEXT pour séparer les étapes d’agrégation lorsque vous devez agréger un résultat agrégé.

Agrégation au sein d’un chemin apparié

Une variable d’arête limitée par un motif de longueur variable devient une liste de groupes. Un agrégat sur cette variable est horizontal : il calcule un résultat dans la liste pour chaque chemin correspondant au lieu de combiner différentes lignes d’entrée.

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN COUNT(knows) AS pathLength

Ici, COUNT(knows) retourne le nombre d’arêtes dans chaque chemin correspondant. Les formes horizontales de COUNT, SUM, AVG, MIN, MAX, COLLECT_LIST, COLLECT_ONE, et COLLECT_ELEMENTS sont soutenues. COUNT(*) et spécifiques FILTER à l’agrégat ou LIMIT ne sont pas des formes horizontales.

Un agrégat horizontal peut être l’entrée d’un agrégat vertical extérieur :

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN MIN(COUNT(knows)) AS shortestMatchedPath

Dans cette requête, COUNT(knows) calcule une longueur par chemin apparié, et MIN combine ces longueurs sur les lignes d’entrée.

Pour des exemples orientés tâches, voir Filtrer et agréger les données de graphes.

Expressions conditionnelles

Utilisez une expression simple CASE pour comparer une expression avec une ou plusieurs valeurs et retourner le résultat associé à la première valeur égale :

CASE expression
  WHEN value1 THEN result1
  WHEN value2 THEN result2
  ELSE default_result
END

NULLIF :

NULLIF(a, b) retourne NULL si a la valeur est bégale , sinon retourne a.

Exemple :

MATCH (p:Person)
RETURN p.firstName,
       CASE p.gender
         WHEN 'male' THEN 'M'
         WHEN 'female' THEN 'F'
         ELSE 'Other'
       END AS gender_code,
       NULLIF(p.browserUsed, 'Unknown') AS browser

Les expressions recherchées CASE WHEN <predicate> ne sont pas prises en charge. Pour router les lignes par prédicats et exécuter une requête ou une procédure imbriquée pour la branche sélectionnée, utilisez une WHEN instruction conditionnelle.

Fonctions de chaîne

Utilisez des fonctions de chaîne pour mesurer, transformer, rechercher, comparer et combiner des chaînes de caractères.

Longueur du caractère et affaire

Utilisez ces fonctions pour mesurer ou modifier les chaînes de caractères :

Function	Descriptif
`CHAR_LENGTH(string)`	Retourne le nombre de caractères.
`UPPER(string)`	Applique un mappage en majuscules Unicode.
`LOWER(string)`	Applique un mappage en minuscules Unicode.
`CASEFOLD(string)`	Applique le pliage Unicode des casse-cas, indépendant de la localité, pour l’appariement sans casse.

Les correspondances Unicode peuvent modifier la longueur ou la représentation d’une chaîne :

RETURN UPPER('straße') AS uppercase,
       LOWER('İ') AS lowercase,
       CASEFOLD('Straße') AS folded

Les résultats sont STRASSErespectivement , i̇, et strasse, . CASEFOLD n’est pas équivalent à LOWER. Par exemple, le pliage de cas correspond ß à ss et mappe les formes Σsigma grecques , σ, et ς vers σ.

Normalisation des chaînes

GQL définit quatre formes de normalisation Unicode :

Forme de normalisation C (NFC), composition canonique.
Forme de normalisation D (NFD), décomposition canonique.
Forme de normalisation KC (NFKC), composition de compatibilité.
Forme de normalisation KD (NFKD), décomposition de compatibilité.

NORMALIZE(string) par défaut, NFC. Spécifions une forme de normalisation comme second argument :

RETURN NORMALIZE('cafe\u0301') AS composed,
       NORMALIZE('café', NFD) AS decomposed

L’argument doit être une ficelle.

Important

Graph prend actuellement en charge la NFC et la NFD. Spécifier NFKC ou NFKD produit une erreur.

Cordages de finition

Utilisez TRIM pour retirer les caractères d’espace ou un caractère spécifié des deux extrémités, du début ou de la fin d’une chaîne :

RETURN TRIM('  text  ') AS both_ends,
       TRIM(BOTH FROM '  text  ') AS explicit_both,
       TRIM(LEADING FROM '  text  ') AS beginning,
       TRIM(TRAILING FROM '  text  ') AS ending,
       TRIM(LEADING 'f' FROM 'foobar') AS custom_character

La valeur de trim personnalisée doit être exactement d’un octet. Les caractères Unicode multioctets et les chaînes contenant plusieurs caractères ne sont pas pris en charge comme valeurs de trim personnalisées. Une source nulle ou une valeur de trim personnalisée renvoie null.

Cordes de jointure

STRING_JOIN(list [, delimiter]) rejoint une liste de ficelles. Le délimiteur par défaut est une virgule suivie d’un espace :

RETURN STRING_JOIN(['foo', 'bar', 'baz']) AS default_delimiter,
       STRING_JOIN(['foo', 'bar', 'baz'], '-') AS custom_delimiter

Les résultats sont foo, bar, baz et foo-bar-baz. Une liste vide renvoie une chaîne vide. Une liste nulle, un délimiteur nul ou un élément de liste nulle rend null. Tout élément de liste non nul doit être une chaîne.

Fonctions d’expression régulière

Graph fournit ces fonctions d’expression régulière comme extensions de GQL :

Function	Utiliser
`MSFT.REGEXP_LIKE`	Vérifiez si le texte contient une correspondance.
`MSFT.REGEXP_COUNT`	Compter les correspondances.
`MSFT.REGEXP_INSTR`	Trouvez la position d’un groupe de correspondance ou de capture.
`MSFT.REGEXP_SUBSTR`	Retournez le texte d’une correspondance ou d’un groupe de capture.
`MSFT.REGEXP_REPLACE`	Remplacez le texte correspondant.

`MSFT.REGEXP_LIKE`

Retour TRUE lorsque le motif correspond à une partie de la chaîne source. Si aucune correspondance n’est trouvée, elle retourne FALSE.

Arguments	Syntax
2	`MSFT.REGEXP_LIKE(source, pattern)`
3	`MSFT.REGEXP_LIKE(source, pattern, flags)`

source est la chaîne à rechercher. pattern est apparié à toute sous-chaîne de source , sauf si l’expression elle-même utilise des ancrages tels que ^ ou $. flags modifie le comportement de correspondance tel que décrit dans les règles et options de correspondance.

RETURN MSFT.REGEXP_LIKE('HELLO', 'hello', 'i') AS matches

Le résultat est TRUE.

`MSFT.REGEXP_COUNT`

Ça renvoie le nombre de correspondances. Si aucune correspondance n’est trouvée, elle retourne 0.

Arguments	Syntax
2	`MSFT.REGEXP_COUNT(source, pattern)`
3	`MSFT.REGEXP_COUNT(source, pattern, start)`
4	`MSFT.REGEXP_COUNT(source, pattern, start, flags)`

source est la chaîne à rechercher, et pattern identifie les correspondances à compter. start est la position Unicode de code à base zéro à partir de laquelle l’appariement peut commencer. Une partie doit commencer à cette position ou après. Cette position ne devient pas un nouveau départ pour les motifs ancrés. flags modifie le comportement de correspondance tel que décrit dans les règles et options de correspondance.

RETURN MSFT.REGEXP_COUNT('1a2a3a4', '[0-9]', 3) AS match_count

La recherche commence à la position 3, la seconde a, donc seuls les chiffres 3 et 4 sont comptés. Le résultat est 2.

`MSFT.REGEXP_INSTR`

Retourne la position à zéro d’un groupe de correspondance ou de capture sélectionné.

Arguments	Syntax
2	`MSFT.REGEXP_INSTR(source, pattern)`
3	`MSFT.REGEXP_INSTR(source, pattern, start)`
4	`MSFT.REGEXP_INSTR(source, pattern, start, occurrence)`
5	`MSFT.REGEXP_INSTR(source, pattern, start, occurrence, return_option)`
6	`MSFT.REGEXP_INSTR(source, pattern, start, occurrence, return_option, flags)`
7	`MSFT.REGEXP_INSTR(source, pattern, start, occurrence, return_option, flags, group)`

source est la chaîne à rechercher, et pattern identifie les correspondances. start est la position Unicode de code à base zéro à partir de laquelle l’appariement peut commencer. Une correspondance doit commencer à cette position ou après, ce qui ne constitue pas un nouveau départ de la corde pour les motifs ancrés.

occurrence sélectionne la première, la deuxième ou la correspondance non superposante suivante trouvée parmi start. group Sélectionne ce qu’il faut localiser dans cette correspondance : 0 sélectionne la correspondance complète, et une valeur positive sélectionne ce groupe de capture numéroté. return_option détermine quelle frontière de la correspondance ou du groupe sélectionné est retournée : 0 renvoie sa position de départ, puis 1 retourne la position immédiatement après sa fin. flags modifie le comportement de correspondance tel que décrit dans les règles et options de correspondance.

Si aucune occurrence correspondante n’est trouvée, ou si le groupe de capture sélectionné ne participe pas à cette occurrence, la fonction retourne -1.

RETURN MSFT.REGEXP_INSTR('banana', 'a', 0, 2) AS match_position

La deuxième partie commence à la position 3, donc le résultat est 3.

`MSFT.REGEXP_SUBSTR`

Retourne le texte d’une correspondance ou d’un groupe de capture sélectionné.

Arguments	Syntax
2	`MSFT.REGEXP_SUBSTR(source, pattern)`
3	`MSFT.REGEXP_SUBSTR(source, pattern, start)`
4	`MSFT.REGEXP_SUBSTR(source, pattern, start, occurrence)`
5	`MSFT.REGEXP_SUBSTR(source, pattern, start, occurrence, flags)`
6	`MSFT.REGEXP_SUBSTR(source, pattern, start, occurrence, flags, group)`

occurrence sélectionne la première, la deuxième ou la correspondance non superposante suivante trouvée parmi start. group sélectionne le texte à retourner de cette correspondance : 0 sélectionne la correspondance complète, et une valeur positive sélectionne ce groupe de capture numéroté. flags modifie le comportement de correspondance tel que décrit dans les règles et options de correspondance.

Si aucune occurrence correspondante n’est trouvée, ou si le groupe de capture sélectionné ne participe pas à cette occurrence, la fonction retourne nulle.

RETURN MSFT.REGEXP_SUBSTR(
  '12-345',
  '([0-9]+)-([0-9]+)',
  0,
  1,
  '',
  2
) AS matched_text

La première occurrence est la chaîne complète, et le groupe 2 de capture est 345, donc le résultat est 345.

`MSFT.REGEXP_REPLACE`

Ça remplace le texte correspondant. Par défaut, il remplace chaque correspondance et insère littéralement le texte de remplacement.

Arguments	Syntax
3	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement)`
4	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement, start)`
5	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement, start, occurrence)`
6	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement, start, occurrence, flags)`

source est la chaîne à modifier, et pattern identifie les correspondances. replacement est le texte inséré pour une correspondance sélectionnée. EXACT il l’insère littéralement ; TEMPLATE il interprète les références de capture.

start est la position Unicode basée sur zéro à partir de laquelle le remplacement peut commencer. Une partie doit commencer à cette position ou après. Le texte d’avant start est conservé inchangé, et la position ne devient pas un nouveau début de la chaîne pour les motifs ancrés. Définissez occurrence pour 0 remplacer chaque correspondance de start, ou vers une valeur positive pour remplacer uniquement cette correspondance numérotée non chevauchante. Les matchs antérieurs start restent inchangés lorsqu’une occurrence spécifique est sélectionnée. flags modifie le comportement de correspondance tel que décrit dans les règles et options de correspondance.

RETURN MSFT.REGEXP_REPLACE('a1b2c3', '[0-9]', '#', 0, 2) AS replaced

Seule la correspondance du deuxième chiffre est remplacée, donc le résultat est a1b#c3.

Si aucune correspondance n’est trouvée, la chaîne source est retournée inchangée.

Pour réutiliser le texte correspondant dans le remplacement, spécifiez TEMPLATE. Dans ce mode, \0\9 il s’agit de faire référence au match complet et aux groupes de capture, et \\ insère littéralement une barre oblique inverse. Utilisez une chaîne brute littérale, préfixée de @, pour passer ces références sans échapper supplémentaire :

RETURN MSFT.REGEXP_REPLACE(
  'John Smith',
  @'([A-Za-z]+) ([A-Za-z]+)',
  TEMPLATE @'\2 \1'
) AS reordered_name

Le résultat est Smith John.

Règles et options d’appariement

Les patrons utilisent la syntaxe d’expression régulière RE2 et correspondent aux chaînes Unicode. La source peut être n’importe quelle expression de chaîne. Le motif, les drapeaux et le remplacement doivent être des littéraux de chaîne, et les options numériques doivent être des littéraux entiers sans signe.

Les correspondances se trouvent de gauche à droite sans chevauchement. Après une correspondance de longueur nulle, l’appariement avance d’un point de code Unicode.

Les positions de départ et les positions retournées sont des décalages de points de code Unicode basés sur zéro. Les nombres d’occurrence sont basés sur un seul, sauf que l’occurrence 0 signifie remplacer chaque occurrence dans MSFT.REGEXP_REPLACE.

Le tableau suivant liste les valeurs par défaut pour les arguments optionnels omis :

Function	Defaults
`MSFT.REGEXP_LIKE`	Les drapeaux sont vides.
`MSFT.REGEXP_COUNT`	Début est `0`; les drapeaux sont vides.
`MSFT.REGEXP_INSTR`	Start est `0`; occurrence est `1`; option retour est `0`; les drapeaux sont vides ; le groupe est `0`.
`MSFT.REGEXP_SUBSTR`	Début est `0`; occurrence est `1`; les drapeaux sont vides ; le groupe est `0`.
`MSFT.REGEXP_REPLACE`	Le mode est `EXACT`; le point de départ est `0`; l’occurrence est `0`; les drapeaux sont vides.

Les drapeaux optionnels sont :

Flag	Comportement
`i`	Matchez sans égard à l’affaire.
`m`	Faites `^` et `$` faites correspondre le début et la fin de chaque ligne.
`s`	Faites correspondre `.` les personnages de la nouvelle ligne.

Combinez les drapeaux dans une même chaîne, comme 'ims'. Une source nulle renvoie nulle. Un drapeau non supporté, une expression régulière invalide, une option de retour invalide, ou une occurrence ou un numéro de groupe invalides renvoient une erreur.

Fonctions graphiques

nodes(path) - retourne des nœuds à partir d’une valeur de chemin d’accès.
edges(path) - retourne des arêtes à partir d’une valeur de chemin d’accès.
elements(path) - retourne tous les nœuds et arêtes d’un chemin sous la forme d’une seule liste, dans l’ordre du chemin.
labels(node_or_edge) - retourne les étiquettes d’un nœud ou d’un bord sous forme de liste de chaînes.
path_length(path) - retourne le nombre de bords dans un chemin d’accès.
element_id(node_or_edge) - renvoie l’identifiant de nœud ou d’arête comme une chaîne opaque.

ELEMENT_ID accepte une référence de nœud ou d’arête et retourne null pour une entrée nulle. Traitez la corde retournée comme opaque.

Exemple :

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

Fonctions de liste

size(list) - retourne la taille d’une valeur de liste.
trim(list,n) - raccourcit une liste à au plus n des éléments.

Exemple :

MATCH (p:Person)-[:hasInterest]->(t:Tag)
LET personId = p.id, personName = p.firstName
RETURN personId, personName, collect_list(t.name) AS interests
GROUP BY personId, personName
FILTER size(interests) > 3

Fonctions temporelles

CURRENT_TIMESTAMP - retourne la datetime en zone actuelle.
ZONED_DATETIME(string) - renvoie l’heure de date zonée représentée par une chaîne ISO 8601.
DURATION(string) - renvoie la durée diurne représentée par une chaîne de durée ISO 8601.

Exemple :

RETURN CURRENT_TIMESTAMP AS now,
       DURATION('PT2H') AS twoHours

Utilisez l’opérateur de soustraction pour obtenir une durée entre deux dates de zone :

RETURN ZONED_DATETIME('2026-09-17T12:00:00Z')
       - ZONED_DATETIME('2026-09-17T10:00:00Z') AS elapsed

Important

Graph prend en compte les durées diurnes mais pas les durées année-mois. DURATION_BETWEEN(start, end) n’est pas actuellement pris en charge ; soustrayez plutôt les deux valeurs de date-heure zonées.

Fonctions génériques

coalesce(value1, value2, ...) - retourne la première valeur non null.
to_json_string(value) : convertit une valeur en sa représentation sous forme de chaîne JSON.

Exemple :

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

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-09-29

Arguments	Syntax
3	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement)`
4	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement, start)`
5	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement, start, occurrence)`
6	`MSFT.REGEXP_REPLACE(source, pattern, [EXACT \\| TEMPLATE] replacement, start, occurrence, flags)`

Expressions, prédicats et fonctions GQL

Littéraux

Predicates

Prédicats de comparaison

Expression logiques

Prédicats d’existence de propriété

Sous-requêtes d’existence

Répertorier les prédicats d’appartenance

Fonctions prédicatives à liste

Prédicats de modèle de chaîne

Expressions arithmétiques

Accès à la propriété

Lister l’accès

Fonctions intégrées

Fonctions numériques

Valeur absolue et puissance

Fonctions trigonométriques

Plages d’entiers

Fonctions d'agrégation

Quantificateurs d’ensembles

Filtres et limites spécifiques à l’agrégat

Agrégation entre lignes

Agrégation au sein d’un chemin apparié

Expressions conditionnelles

Fonctions de chaîne

Longueur du caractère et affaire

Normalisation des chaînes

Cordages de finition

Cordes de jointure

Fonctions d’expression régulière

MSFT.REGEXP_LIKE

MSFT.REGEXP_COUNT

MSFT.REGEXP_INSTR

MSFT.REGEXP_SUBSTR

MSFT.REGEXP_REPLACE

Règles et options d’appariement

Fonctions graphiques

Fonctions de liste

Fonctions temporelles

Fonctions génériques

Contenu connexe

Commentaires

Ressources supplémentaires

`MSFT.REGEXP_LIKE`

`MSFT.REGEXP_COUNT`

`MSFT.REGEXP_INSTR`

`MSFT.REGEXP_SUBSTR`

`MSFT.REGEXP_REPLACE`