Guide

Neo4j, graphes, Cypher et versions par calendrier

Neo4j stocke les données sous forme de graphe interrogé en Cypher. Versions par calendrier, GQL, quand préférer un graphe, éditions, modélisation et GraphRAG.

L'équipe CodeWorlds14 min de lecture ·

Pratique NestJS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article11

Neo4j stocke les données sous forme de nœuds reliés par des relations, où une relation est une entité de premier rang avec son propre type et ses propres propriétés. Les requêtes s'écrivent en Cypher, qui décrit des motifs dans un graphe plutôt que des jointures entre tables.

Avant d'ouvrir la documentation, deux choses ont assez changé pour que les anciens contenus induisent en erreur : la façon dont les versions sont numérotées, et le fait que le langage de requête porte désormais sa propre version, indépendante de la base de données.

Versions par calendrier, la fin des numéros

Après la sortie de la version cinq avec support à long terme, le projet est passé à un versionnement par date. Une version est désormais nommée par l'année, le mois et le numéro de correctif, la version de juin 2026 par exemple.

La conséquence pratique est unique et à retenir : il n'existe pas de Neo4j 6. Les contenus qui parlent de passer à la six sont soit un malentendu, soit antérieurs au changement. Si vous cherchez la dernière version, vous cherchez une date et non un numéro.

La deuxième conséquence concerne la planification des mises à jour. Les versions paraissent chaque mois, donc la question de savoir si vous êtes sur la version courante n'a pas le même poids que pour un projet qui publie une fois par an. Décidez si vous suivez chaque version ou si vous restez sur une ligne à support à long terme, et inscrivez-le dans le processus de maintenance.

La troisième concerne la lecture de la documentation. Les pages de changements sont désormais organisées par séries annuelles, donc retrouver le comportement d'une fonctionnalité précise exige de savoir quelle série vous faites tourner.

Un Cypher avec sa propre version et le standard GQL

C'est un changement rarement vu dans les bases de données et sa raison mérite d'être comprise.

Le langage de requête porte désormais son propre versionnement, indépendant de la base. La version cinq du langage est celle connue des versions précédentes, et vingt-cinq est la plus récente, nommée d'après l'année de son introduction.

Le gain est que mettre à jour la base ne force pas à changer les requêtes. Vous pouvez monter la version du serveur en laissant les requêtes sur l'ancienne version du langage, et passer à la nouvelle séparément, quand cela vous convient. Cela résout le problème qui fait le plus mal avec les bases de données : une mise à jour qui exige des changements simultanés de code à des dizaines d'endroits.

Le second fil est la convergence avec le standard GQL, une norme internationale pour les langages de requête de graphes. Cypher en a été le principal point de référence, et la nouvelle version du langage s'en rapproche aussi par la syntaxe, en ajoutant une construction d'itération de la norme à côté de celle qui existait.

Pour un utilisateur, cela compte pour évaluer le risque de dépendance à un éditeur. Un langage décrit par une norme est plus facile à quitter qu'un langage possédé par une seule entreprise, bien qu'en pratique les différences entre implémentations restent assez grandes pour que la migration ne soit pas indolore.

Quand un graphe l'emporte sur des tables

Cela vaut la peine d'être tranché concrètement, car une base de graphes est parfois choisie par fascination plutôt que par besoin.

Un graphe l'emporte là où la question porte sur un chemin plutôt que sur une ligne. « Comment cette personne est-elle liée à celle-là », « par combien d'intermédiaires passe cet argent », « que recommander à quelqu'un d'après ce qu'ont acheté des gens qui lui ressemblent ». Dans une base relationnelle, chacune de ces questions revient à joindre une table à elle-même plusieurs fois, et le coût croît de façon exponentielle avec le nombre de niveaux.

Un graphe l'emporte aussi avec des structures qui changent de forme. Ajouter un nouveau type de lien entre des entités existantes revient à ajouter une relation plutôt qu'à migrer un schéma.

Un graphe perd sur les requêtes qui couvrent tout : sommes, moyennes, rapports pour une période. Là, une base relationnelle avec un index adapté est plus rapide et plus simple.

Il perd aussi sur des données fondamentalement tabulaires. Une liste de commandes avec ses lignes est une relation un à plusieurs et non un graphe, et la modéliser en graphe ajoute de la complexité sans gain.

Le test pratique se formule ainsi : si vos questions contiennent « à travers », « indirectement » ou « combien d'étapes », un graphe a du sens. Si elles contiennent « combien » et « pour la période », restez avec PostgreSQL.

Cypher en pratique

CYPHER
MATCH (person:Person {email: $email})-[:WORKS_AT]->(company:Company)
      <-[:WORKS_AT]-(colleague:Person)
WHERE colleague <> person
RETURN colleague.name, company.name
LIMIT 20

La syntaxe décrit un motif comme un dessin : les parenthèses rondes sont des nœuds, les flèches sont des relations, et le sens de la flèche compte. C'est la plus grande force de ce langage, car une requête se lit comme une phrase sur la structure.

Trois choses valent d'être connues dès le départ.

Le sens d'une relation peut être omis lors d'une recherche, en écrivant sans flèche, et avec des relations symétriques c'est généralement nécessaire. Laisser un sens là où les données ont été écrites dans l'autre renvoie un résultat vide sans aucune erreur.

Limiter la longueur des chemins est obligatoire pour une recherche en profondeur. Une requête qui cherche des liens sans limite d'étapes peut parcourir tout le graphe sans jamais revenir, et sur un grand ensemble elle peut bloquer le serveur.

Les étiquettes de nœuds et les types de relations méritent un nommage cohérent, car ce sont elles qui permettent au planificateur de restreindre la recherche. Une requête sans étiquette part de tous les nœuds de la base.

Éditions et ce que chacune contient

La séparation entre les éditions communautaire et commerciale est la décision opérationnelle la plus importante ici et mérite d'être connue avant de commencer.

L'édition communautaire est gratuite et suffit pour apprendre, faire des prototypes et de plus petits déploiements sur une seule machine. Vous obtenez le langage de requête complet, les pilotes et l'outillage.

Ce qui lui manque : le clustering, c'est-à-dire le fonctionnement sur plusieurs serveurs, le contrôle d'accès par rôles, les sauvegardes faites sans arrêter la base, et certaines capacités d'administration.

Deux effets pratiques en découlent. Sans clustering, la disponibilité repose sur une seule machine, donc sa panne est une interruption de service. Sans sauvegarde en ligne, faire une copie exige une fenêtre de maintenance, ce qui pour une base qui fonctionne en continu est un problème.

Pour un déploiement en production avec une exigence de continuité, cela tranche généralement en faveur de l'édition commerciale ou d'une variante cloud gérée. Pour un outil interne, une analyse ou un prototype, l'édition gratuite convient et mérite d'être utilisée sans le sentiment qu'elle est amputée jusqu'à l'inutilité.

Modélisation, ou les décisions prises au départ

Un modèle de graphe semble sans forme imposée, et c'est exactement pourquoi il invite à des décisions qui se vengent un an plus tard.

La première concerne ce qui est un nœud et ce qui est une propriété. Une ville stockée comme propriété d'une personne est une chaîne sur laquelle on peut filtrer et rien de plus. Une ville comme nœud propre permet de demander qui d'autre y habite et ce qui d'autre se rattache à cette ville. La règle pratique : si vous allez interroger les liens d'une chose, c'est un nœud ; si seulement sa valeur, c'est une propriété.

La deuxième concerne le sens des relations. Dans un graphe, une relation a toujours un sens, même quand le concept est symétrique, donc une connaissance entre deux personnes doit être stockée dans un sens tandis que les requêtes doivent éviter d'imposer ce sens. Stocker les deux sens double les données et crée une occasion de dérive.

La troisième concerne les propriétés sur les relations. La date de début d'une collaboration ou le poids d'un lien appartiennent à la relation plutôt qu'à l'un ou l'autre des nœuds, et c'est l'une des choses qu'un modèle relationnel n'exprime pas directement. L'utiliser est ce qui sépare un bon modèle de graphe d'une table transcrite en nœuds.

La quatrième concerne les nœuds avec très beaucoup de liens. Un nœud qui représente une catégorie populaire ou un pays peut contenir des millions de relations, et chaque requête qui passe par lui doit les parcourir. Le remède est généralement de découper ce nœud selon un critère supplémentaire, ou de router la requête en le contournant.

Maintenance et performance

Quelques points opérationnels qui fonctionnent ici autrement que dans une base relationnelle.

Les index se créent sur les propriétés des nœuds portant une étiquette donnée et servent un seul but : trouver un point de départ. Parcourir des relations n'exige aucun index, car une relation est un pointeur physique. C'est pourquoi la performance d'une requête de graphe dépend surtout de la rapidité avec laquelle on atteint le premier nœud.

Les contraintes d'unicité jouent un double rôle : elles protègent les données et créent un index au passage. Elles valent d'être placées sur des identifiants naturels, car sans elles des nœuds en double apparaissent discrètement quand les mêmes données sont chargées plus d'une fois.

Charger de grands jeux de données exige de découper le travail en lots. Une seule transaction qui insère un million de nœuds épuisera la mémoire et tombera, alors que des lots de quelques milliers se comportent de façon prévisible.

Le plan d'exécution d'une requête peut être inspecté, et cela vaut la peine pour chaque requête destinée à la production. Il montre de quel nœud la recherche part et combien d'éléments elle parcourt à chaque étape, et cela explique généralement la différence entre une requête qui prend des millisecondes et une qui ne revient jamais.

Neo4j face aux alternatives

OptionModèleLicenceÀ choisir quand
Neo4jGraphe natif, CypherCommunautaire ou commercialeQuestions sur des chemins et des liens
PostgreSQL avec récursionTables plus requêtes récursivesOuverteLe graphe est un ajout plutôt que le but
Bases de graphes embarquéesUn graphe dans le processus de l'applicationGénéralement ouverteUn petit graphe, sans service séparé
Zep avec GraphitiUn graphe temporel sur cette baseBibliothèque ouverteMémoire d'agent plutôt que graphe général

La deuxième ligne mérite un examen honnête avant d'ajouter une autre base à la pile. Les requêtes récursives d'une base relationnelle gèrent le parcours de hiérarchies et les chemins peu profonds, et avec une structure arborescente elles suffisent souvent. Le gain est que vous ne montez pas de seconde base, n'en synchronisez aucune et n'en maintenez aucune.

La frontière se situe à la profondeur et au nombre de types de liens. Trois niveaux à travers un seul type de relation, une base relationnelle s'en charge. Six niveaux à travers quatre types de relations différents, c'est là qu'un graphe commence à gagner nettement.

La dernière ligne rappelle que cette base sous-tend parfois d'autres outils. Une couche de mémoire d'agent construite sur un graphe temporel peut tourner dessus, ce qui vaut d'être su pour choisir une solution de mémoire, car cela signifie une base de plus à maintenir.

Recherche vectorielle et graphes de connaissances

La base prend en charge un type vectoriel et un index de recherche par similarité, ce qui a un usage concret dans les applications construites sur des modèles de langage.

Le cœur de l'idée est de combiner deux méthodes de recherche. La similarité sémantique trouve les fragments qui correspondent à la question, et le parcours des relations ajoute un contexte que le fragment lui-même n'avait pas : qui est l'auteur, à quel projet le document appartient, ce qui en découle d'autre.

C'est l'avantage sur un magasin de vecteurs ordinaire, où les fragments sont indépendants et où le modèle reçoit cinq paragraphes sans aucune information sur leur relation.

Le prix est qu'il faut construire le graphe, ce qui exige d'extraire des entités et des relations du texte, généralement avec un modèle. Le coût de cette étape croît avec le nombre de documents et dépasse souvent le coût de la recherche elle-même.

La réalisation la plus connue de cette idée est GraphRAG, où le graphe d'entités est découpé en communautés et un modèle résume chacune pour que l'on puisse répondre à des questions sur l'ensemble du corpus plutôt que sur un seul fragment. L'indexation seule se chiffre en centaines de dollars pour mille documents, et elle revient à chaque changement important de la collection, donc en pratique on se tourne vers des variantes qui reportent le résumé au moment de la requête.

Conseil pratique : cette approche rapporte avec des documents entre lesquels des liens existent réellement et valent d'être cherchés. Pour un ensemble d'articles d'aide indépendants, un magasin de vecteurs ordinaire ou une extension d'une base relationnelle suffit et coûte moins.

Erreurs courantes

La première est de chercher la version 6 de Neo4j. Après la cinq à support long terme, la numérotation est passée aux versions par calendrier, donc on cherche une date et non un numéro.

La deuxième est une requête de recherche de chemins sans limite d'étapes. Sur un grand graphe, elle peut tout parcourir et bloquer le serveur.

La troisième est de laisser le sens d'une relation là où les données ont été écrites dans l'autre. Le résultat est vide sans erreur, donc la cause est cherchée dans les données plutôt que dans la requête.

La quatrième est de modéliser des données tabulaires en graphe. Une liste de commandes avec ses lignes est une relation un à plusieurs, et un graphe n'y apporte rien d'autre qu'une base de plus à maintenir.

La cinquième est de déployer l'édition communautaire là où la continuité est requise. Sans clustering ni sauvegarde en ligne, cela signifie une interruption en cas de panne et pendant les sauvegardes.

La sixième est d'omettre les étiquettes de nœuds dans les requêtes. Sans elles, le planificateur part de tous les nœuds de la base, et une requête qui fonctionnait sur mille nœuds cesse de fonctionner sur un million.

FAQ

Quelle est la dernière version de Neo4j ?

Les versions sont par calendrier depuis 2025, au format année, mois et correctif, donc la dernière est la date la plus récente et non le numéro le plus élevé. Il n'y a pas de Neo4j 6, et les contenus qui parlent de passer à la six sont antérieurs à ce changement.

Qu'est-ce que Cypher 25 ?

Une version du langage de requête, nommée d'après l'année de son introduction et versionnée indépendamment de la base de données. Cela signifie que monter la version du serveur ne force pas à changer toutes les requêtes d'un coup, car l'ancienne version du langage peut rester pendant que vous passez à la nouvelle séparément.

L'édition communautaire suffit-elle en production ?

Pour des déploiements sur une seule machine sans exigence de continuité, oui. Il lui manque le clustering, le contrôle d'accès par rôles et les sauvegardes sans arrêt de la base, donc là où la disponibilité et des sauvegardes régulières sont requises, il faut l'édition commerciale ou une variante gérée.

Quand un graphe est-il meilleur qu'une base relationnelle ?

Quand les questions portent sur des chemins et des liens sur de nombreux niveaux plutôt que sur des sommes et des moyennes. Le test pratique : si vos questions contiennent « à travers », « indirectement » ou « combien d'étapes », un graphe a du sens. Pour des rapports par période, PostgreSQL est plus rapide et plus simple.

Cela remplacera-t-il une base vectorielle ?

Pour les graphes de connaissances, où les liens entre fragments comptent autant que la similarité, cela apporte plus qu'un magasin de vecteurs ordinaire. Pour un ensemble de documents indépendants sans relations significatives, c'est un excès, et le coût de construction du graphe dépasse le gain.

La documentation se trouve sur le site du projet, et les changements de la série actuelle dans le manuel d'exploitation.

À lire aussi