Neo4j, graphs, Cypher and calendar versioning

Neo4j, graphs, Cypher and calendar versioning

Neo4j stores data as nodes connected by relationships, where a relationship is a first class entity with its own type and its own properties. Queries are written in Cypher, which describes patterns in a graph rather than joins between tables.

Before reaching for the documentation, two things changed enough that older material misleads: how versions are numbered, and the fact that the query language now carries its own version, independent of the database.

Calendar versions, the end of numbers

After the release of five with long term support, the project moved to date based versioning. A version is now named by year, month, and patch number, the June 2026 release for instance.

The practical consequence is singular and worth remembering: there is no such thing as Neo4j 6. Material talking about upgrading to six is either a misunderstanding or predates the change. If you are looking for the latest version, you are looking for a date rather than a number.

The second consequence concerns upgrade planning. Releases appear monthly, so the question of whether you are on the current version carries different weight from a project releasing once a year. Decide whether you follow every release or stay on a long term supported line, and write that into the maintenance process.

The third concerns reading documentation. Change pages are now organised by annual series, so finding the behaviour of a particular feature requires knowing which series you run.

Cypher with its own version and the GQL standard

This is a change rarely seen in databases and the reason for it deserves understanding.

The query language now carries its own versioning, independent of the database. Version five of the language is the one known from previous releases, and twenty five is the newer one, named after the year of its introduction.

The gain is that upgrading the database does not force changing queries. You can raise the server version while leaving queries on the older language version, and move to the newer one separately, when it suits you. That solves the problem that hurts most with databases: an upgrade requiring simultaneous code changes in dozens of places.

The second thread is convergence with the GQL standard, an international norm for graph query languages. Cypher was its main reference point, and the newer language version approaches it in syntax too, adding an iterating construct from the standard alongside the existing one.

For a user that matters when assessing vendor lock in risk. A language described by a norm is easier to move away from than a language owned by one company, though in practice differences between implementations remain large enough that migration is not painless.

When a graph beats tables

Worth settling concretely, since a graph database sometimes gets chosen out of fascination rather than need.

A graph wins where the question concerns a path rather than a row. "How is this person connected to that one", "through how many intermediaries does this money pass", "what to recommend to somebody based on what people like them bought". In a relational database each of those is joining a table to itself several times, and the cost grows exponentially with the number of levels.

A graph also wins with structures that change shape. Adding a new kind of connection between existing entities means adding a relationship rather than migrating a schema.

A graph loses on queries covering everything: sums, averages, reports for a period. There a relational database with a suitable index is faster and simpler.

It also loses on data that is fundamentally tabular. A list of orders with line items is a one to many relation rather than a graph, and modelling it as a graph adds complexity with no gain.

The practical test reads: if your questions contain "through", "indirectly", or "how many steps", a graph makes sense. If they contain "how many" and "for the period", stay with PostgreSQL.

Cypher in practice

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

The syntax describes a pattern as a drawing: round brackets are nodes, arrows are relationships, and arrow direction matters. That is this language's greatest strength, since a query reads as a sentence about structure.

Three things deserve knowing from the start.

Relationship direction can be omitted when searching, by writing without an arrow, and with symmetric relationships that is usually necessary. Leaving a direction where the data was written the other way returns an empty result with no error at all.

Limiting path length is mandatory when searching in depth. A query looking for connections with no step limit can traverse the entire graph and never return, and on a large set can block the server.

Node labels and relationship types deserve consistent naming, since they are what lets the planner narrow the search. A query with no label starts from every node in the database.

Editions and what each contains

The split between community and commercial editions is the most important operational decision here and deserves knowing before starting.

The community edition is free and suffices for learning, prototypes, and smaller single machine deployments. You get the full query language, drivers, and tooling.

What it lacks: clustering, meaning operation across several servers, role based access control, backups taken without stopping the database, and some administrative capabilities.

Two practical effects follow. No clustering means availability rests on one machine, so its failure is downtime. No online backup means taking a copy requires a maintenance window, which for a database running around the clock is a problem.

For a production deployment with a continuity requirement that usually settles the matter in favour of the commercial edition or a managed cloud variant. For an internal tool, an analysis, or a prototype the free edition is fine and deserves using without a sense that it is cut down to uselessness.

Modelling, or the decisions taken at the start

A graph model looks free form, and that is exactly why it invites decisions that take revenge a year later.

The first concerns what is a node and what is a property. A city stored as a person's property is a string you can filter on and nothing more. A city as its own node lets you ask who else lives there and what else connects to that city. The practical rule: if you will ask about something's connections, it is a node; if only about its value, it is a property.

The second concerns relationship direction. In a graph a relationship always has a direction, even when the concept is symmetric, so an acquaintance between two people has to be stored one way round while queries must avoid imposing that direction. Storing both directions doubles the data and creates an opportunity for drift.

The third concerns properties on relationships. The date a collaboration began or the weight of a connection belong to the relationship rather than to either node, and that is one of the things a relational model does not express directly. Using it is what separates a good graph model from a table transcribed into nodes.

The fourth concerns nodes with very many connections. A node representing a popular category or a country can hold millions of relationships, and every query passing through it has to walk them. The remedy is usually splitting such a node by an additional criterion, or routing the query around it.

Maintenance and performance

A few operational things that work differently here than in a relational database.

Indexes are created on properties of nodes carrying a given label and serve one purpose: finding a starting point. Traversing relationships needs no index, since a relationship is a physical pointer. That is why the performance of a graph query depends mainly on how quickly you reach the first node.

Uniqueness constraints play a double role: they guard the data and create an index along the way. They are worth placing on natural identifiers, since without them duplicate nodes appear quietly when the same data is loaded more than once.

Loading large datasets requires splitting the work into batches. A single transaction inserting a million nodes will exhaust memory and fall over, while batches of a few thousand behave predictably.

A query execution plan can be inspected, and it is worth doing for every query heading to production. It shows which node the search starts from and how many elements it walks at each step, and that usually explains the difference between a query taking milliseconds and one that never returns.

Neo4j against the alternatives

The second row deserves honest consideration before adding another database to the stack. Recursive queries in a relational database handle hierarchy traversal and shallow paths, and with a tree structure they are often sufficient. The gain is that you stand up no second database, synchronise none, and maintain none.

The boundary runs at depth and at the number of connection types. Three levels through one relationship kind a relational database handles. Six levels through four different relationship types is where a graph starts winning clearly.

The last row is a reminder that this database sometimes underpins other tools. An agent memory layer built on a time aware graph can run on it, which is worth knowing when choosing a memory solution, since it means one more database to maintain.

Vector search and knowledge graphs

The database supports a vector type and an index for similarity search, which has a concrete use in applications built on language models.

The idea's core is combining two search methods. Semantic similarity finds fragments matching the question, and traversing relationships adds context the fragment itself lacked: who the author is, which project the document belongs to, what else follows from it.

That is the advantage over an ordinary vector store, where fragments are independent and the model receives five paragraphs with no information about how they relate.

The price is that the graph has to be built, which requires extracting entities and relationships from text, usually with a model. The cost of that step grows with document count and is often larger than the cost of search itself.

The best known realisation of this idea is GraphRAG, where the entity graph is split into communities and a model summarises each one so questions about the whole corpus can be answered rather than questions about a single fragment. Indexing alone runs into hundreds of dollars for a thousand documents there and returns with every larger change to the collection, so in practice people reach for variants that defer summarising until query time.

Practical advice: this approach pays off with documents between which connections genuinely exist and are worth searching. For a set of independent help articles, an ordinary vector store or an extension to a relational database suffices and costs less.

Common mistakes

The first is looking for Neo4j version 6. After five with long term support, numbering moved to calendar versions, so you look for a date rather than a number.

The second is a path searching query with no step limit. On a large graph it can traverse everything and block the server.

The third is a relationship direction left in place where the data was written the other way. The result is empty with no error, so the cause gets sought in the data rather than the query.

The fourth is modelling tabular data as a graph. A list of orders with line items is a one to many relation, and a graph adds nothing here beyond another database to maintain.

The fifth is deploying the community edition where continuity is required. No clustering and no online backup means downtime on failure and during backups.

The sixth is omitting node labels in queries. Without them the planner starts from every node in the database, and a query that worked on a thousand nodes stops working on a million.

FAQ

What is the latest Neo4j version?

Versions have been calendar based since 2025, in a year, month, and patch format, so the latest is the freshest date rather than the highest number. There is no Neo4j 6, and material talking about upgrading to six predates that change.

What is Cypher 25?

A version of the query language, named after the year of its introduction and versioned independently of the database. That means raising the server version does not force changing every query at once, since the older language version can stay while you move to the newer one separately.

Is the community edition enough for production?

For single machine deployments with no continuity requirement, yes. It lacks clustering, role based access control, and backups without stopping the database, so where availability and regular backups are required, the commercial edition or a managed variant is needed.

When is a graph better than a relational database?

When the questions concern paths and connections across many levels rather than sums and averages. The practical test: if your questions contain "through", "indirectly", or "how many steps", a graph makes sense. For period reports PostgreSQL is faster and simpler.

Will this replace a vector database?

For knowledge graphs, where connections between fragments matter alongside similarity, it delivers more than an ordinary vector store. For a set of independent documents with no meaningful relationships it is excess, and the cost of building the graph exceeds the gain.

Documentation sits on the project site, and changes in the current series in the operations manual.