Skip to content

Commit caeeee4

Browse files
JPryce-Aklundhstefano-ottolenghi
JPryce-Aklundh
and
stefano-ottolenghi
authored
Select Cypher version (#1123)
Operations manual PRs mentioned in this PR: - neo4j/docs-operations#2153 - neo4j/docs-operations#2116 TODO: Add clarifying note on Additions page --------- Co-authored-by: Stefano Ottolenghi <stefano.ottolenghi@neo4j.com>
1 parent 3a2dd81 commit caeeee4

File tree

4 files changed

+249
-3
lines changed

4 files changed

+249
-3
lines changed

‎modules/ROOT/content-nav.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* xref:queries/index.adoc[]
77
** xref:queries/concepts.adoc[]
88
** xref:queries/basic.adoc[]
9+
** xref:queries/select-version.adoc[]
910
** xref:queries/composed-queries/index.adoc[]
1011
*** xref:queries/composed-queries/combined-queries.adoc[]
1112
*** xref:queries/composed-queries/conditional-queries.adoc[]

‎modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[[cypher-deprecations-additions-removals-compatibility]]
2-
= Deprecations, additions, and compatibility
2+
= Additions, deprecations, removals, and compatibility
33
:description: all of the features that have been removed, deprecated, added, or extended in different Cypher versions.
44
:test-skip: true // all deprecations would fail.
55

@@ -20,6 +20,7 @@ Replacement syntax for deprecated and removed features are also indicated.
2020
[IMPORTANT]
2121
Cypher 25 was introduced in Neo4j 2025.06 and can only be used on Neo4j 2025.06+ databases.
2222
Features removed in Cypher 25 are still available on Neo4j 2025.06+ databases either by prepending a query with `CYPHER 5` or by having Cypher 5 as the default language for the database.
23+
For more information, see xref:queries/select-version.adoc[].
2324

2425
[[cypher-deprecations-additions-removals-2025.06]]
2526
== Neo4j 2025.06

‎modules/ROOT/pages/queries/index.adoc

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
= Queries
22
:description: This page is an overview of the queries section in the Cypher Manual.
33

4-
This section provides a brief overview of the core concepts of a Cypher query (nodes, relationships, and paths), and examples of how to query a Neo4j graph database.
5-
It also discusses how to compose combined queries using `UNION`, conditional queries using `WHEN` and sequential queries using `NEXT`.
4+
This section provides a brief overview of the core concepts of a Cypher query (nodes, relationships, and paths), along with examples of how to query a Neo4j graph database.
5+
It also explains how to select the version of Cypher in which queries are run, and how to compose combined queries using `UNION`, conditional queries using `WHEN`, and sequential queries using `NEXT`.
66

77
* xref:queries/concepts.adoc[]
88
* xref:queries/basic.adoc[]
9+
* xref:queries/select-version.adoc[]
910
* xref:queries/composed-queries/index.adoc[]
1011
** xref:queries/composed-queries/combined-queries.adoc[]
1112
** xref:queries/composed-queries/conditional-queries.adoc[] label:new[Introduced in Neo4j 2025.06]

‎modules/ROOT/pages/queries/select-version.adoc

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
:description: Information about how to select Cypher version for queries or databases.
2+
3+
= Select Cypher version
4+
5+
Users can specify the version of Cypher in which they want to run their queries, choosing between Cypher 5 and Cypher 25.
6+
The Cypher version can be specified either by configuring a default language for the database or by setting it on a per-query basis.
7+
8+
[[cypher-versions-explained]]
9+
== Cypher 25, Cypher 5, and Neo4j explained
10+
11+
Starting in 2025, the Neo4j server transitioned to a calendar-based versioning system.
12+
This means Neo4j will no longer use its previous semantic versioning and release pattern (e.g., 5.25, 5.26).
13+
Instead, releases from 2025 onwards will follow a *YYYY.MM* format, beginning with version 2025.01 released in January 2025, followed by 2025.02 released in February 2025, and so on.
14+
15+
Cypher 25 is introduced alongside *Neo4j 2025.06*.
16+
It is created as a clone of Cypher 5, but with additional new and updated features, as well as some removed features.
17+
For more information about the new, updated, and removed features included in Cypher 25, see the xref:deprecations-additions-removals-compatibility.adoc#cypher-deprecations-additions-removals-2025.06[Additions, deprecations, removals, and compatibility] page.
18+
19+
Cypher 25 is in an evolving state, and more features will be added to it with future releases of Neo4j.
20+
In the releases following Neo4j 2026.06, features will only be added to Cypher 25; no features will be removed until the next Cypher release.
21+
*Any new Cypher features introduced in Neo4j 2025.06 or later will be exclusively added to Cypher 25.*
22+
23+
Users running Neo4j version 2025.06 or later can choose to run their queries using the previous version of Cypher: Cypher 5.
24+
If so, Neo4j will use Cypher 5 as it existed at the time of the Neo4j 2025.06 release (the release in which Cypher 5 was frozen).
25+
*No new features will be added to Cypher 5* (only performance enhancements and eventual bug fixes may be included in server releases following Neo4j 2025.06).
26+
Cypher 5 users must, therefore, migrate to Cypher 25 in order to access new features.
27+
For information about Cypher 5, see the link:https://neo4j.com/docs/cypher-manual/5/introduction/[Cypher 5 Manual].
28+
29+
[NOTE]
30+
Although Cypher 5 queries are currently supported on Neo4j 2025.06+ databases, they will eventually need to be migrated to Cypher 25, as support for Cypher 5 will be discontinued in a future release (anticipated no earlier than two additional server LTS cycles).
31+
32+
[[select-default-cypher-version]]
33+
== Select the default Cypher version for a database
34+
35+
Databases created on, or migrated to, Neo4j 2025.06 or later will continue to have Cypher 5 as their default language (unless {neo4j-docs-base-uri}/operations-manual/current/configuration/configuration-settings/#config_db.query.default_language[`db.query.default_language`] is set to `CYPHER_25`).
36+
This is true for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/#manage-database-systems[system, standard, and composite] Neo4j databases.
37+
However, it is possible to set a different default language on both new and existing system, standard, and composite databases.
38+
39+
To select a default Cypher version when creating a database, add `DEFAULT LANGUAGE <language version>` to the link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/standard-databases/create-databases/[`CREATE DATABASE`] statement.
40+
41+
[NOTE]
42+
Setting the default language requires the link:{neo4j-docs-base-uri}/operations-manual/current/authentication-authorization/dbms-administration/#access-control-dbms-administration-database-management[`SET DATABASE DEFAULT LANGUAGE` privilege].
43+
44+
.Select default Cypher version when creating a database
45+
[.tabbed-example]
46+
=====
47+
[.include-with-Cypher-25]
48+
======
49+
50+
.Cypher 25
51+
[source,cypher]
52+
----
53+
CREATE DATABASE actors DEFAULT LANGUAGE CYPHER 25
54+
----
55+
56+
======
57+
58+
[.include-with-Cypher-5]
59+
======
60+
61+
.Cypher 5
62+
[source,cypher]
63+
----
64+
CREATE DATABASE movies DEFAULT LANGUAGE CYPHER 5
65+
----
66+
67+
======
68+
=====
69+
70+
To alter the default Cypher version on an existing database, add `SET DEFAULT LANGUAGE <language version>` to the link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/standard-databases/alter-databases/[`ALTER DATABASE`] command.
71+
72+
[NOTE]
73+
Altering the default language requires the link:{neo4j-docs-base-uri}/operations-manual/current/authentication-authorization/dbms-administration/#access-control-dbms-administration-database-management[`SET DATABASE DEFAULT LANGUAGE` privilege].
74+
75+
.Alter the default Cypher version on an existing database
76+
[.tabbed-example]
77+
=====
78+
[.include-with-Cypher-25]
79+
======
80+
81+
.Cypher 25
82+
[source,cypher]
83+
----
84+
ALTER DATABASE movies SET DEFAULT LANGUAGE CYPHER 25
85+
----
86+
87+
======
88+
89+
[.include-with-Cypher-5]
90+
======
91+
92+
.Cypher 5
93+
[source,cypher]
94+
----
95+
ALTER DATABASE actors SET DEFAULT LANGUAGE CYPHER 5
96+
----
97+
98+
======
99+
=====
100+
101+
Selecting `CYPHER 25` ensures that all queries run on that database will be executed using the language as it exists in the version of Neo4j that the database is currently running, provided it is on Neo4j 2025.06 or later (unless a query is prepended with xref:selection-query-cypher-version[`CYPHER 5`], which overrides this default).
102+
103+
Selecting `CYPHER 5` as the default database language ensures that all queries run on that database uses the language as it existed at the time of the Neo4j 2025.06 release (unless a query is prepended with xref:selection-query-cypher-version[`CYPHER 25`], which overrides this default).
104+
Any changes introduced after the 2025.06 release will not affect the semantics of the query.
105+
106+
[[config-database-upgrades]]
107+
== Cypher versions, configuration settings, and DBMS upgrades
108+
109+
Changing the Cypher version of new databases in a DBMS can also be done with the setting link:{neo4j-docs-base-uri}/operations-manual/current/configuration/configuration-settings/#config_db.query.default_language[`db.query.default_language`] (default value: `CYPHER_5`).
110+
This setting determines the default language for new databases where it has not been specified as part of a `CREATE` or `ALTER` database command.
111+
For example, `config_db.query.default_language=CYPHER_25` will set Cypher 25 as the default language for a DBMS.
112+
For more information about using configuration settings, see the link:{neo4j-docs-base-uri}/operations-manual/current/configuration/[Operations Manual -> Configuration].
113+
114+
The table below outlines which Cypher version is assigned to databases in different upgrade or installation scenarios:
115+
116+
[cols="3", options="header"]
117+
|===
118+
| Scenario | `db.query.default_language` | Databases
119+
120+
121+
| *Standard DBMS upgrade to Neo4j 2025.06+*
122+
| Unset
123+
| *Existing system database:* `CYPHER 5` +
124+
*Existing user databases:* `CYPHER 5` +
125+
*New user databases default:* `CYPHER 5`
126+
127+
128+
| *Custom DBMS upgrade to Neo4j 2025.06+*
129+
| Manually set to `CYPHER_25` by administrator
130+
| *Existing system database:* `CYPHER 5` +
131+
*Existing user databases:* `CYPHER 5` +
132+
*New user databases default:* `CYPHER 25`
133+
134+
135+
| *New installation of Neo4j 2025.06+*
136+
| Set to `CYPHER_5`
137+
| *New system database:* `CYPHER 5` +
138+
*New user databases default:* `CYPHER 5`
139+
140+
141+
|===
142+
143+
For more information about upgrading and migrating Neo4j databases, see the link:{neo4j-docs-base-uri}/upgrade-migration-guide/current/[Upgrade and migration guide].
144+
145+
[[migrate-queries-from-5-to-25]]
146+
== Migrating queries from Cypher 5 to Cypher 25
147+
148+
It is recommended to modify queries that depend on features deprecated in Cypher 5 and removed in Cypher 25 to align with the changes introduced in Cypher 25.
149+
150+
For example, Cypher 25 disallowed using a `NODE` or `RELATIONSHIP` instead of a `MAP` on the RHS of a xref:clauses/set.adoc[`SET`] clause, and instead requires the xref:functions/scalar.adoc#functions-properties[`properties()`] function to get the map of properties from nodes or relationships before referencing them in a `SET` clause.
151+
The following example demonstrates how a query that works in Cypher 5 can be rewritten to work in Cypher 25.
152+
153+
.Original Cypher 5 query
154+
[source, cypher, role=test-skip]
155+
----
156+
MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
157+
SET n = r
158+
----
159+
160+
.Modified Cypher 25 query
161+
[source, cypher]
162+
----
163+
MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
164+
SET n = properties(r)
165+
----
166+
167+
Another option is to prepend individual queries with a specific language version.
168+
169+
[[selection-query-cypher-version]]
170+
== Select Cypher version for individual queries
171+
172+
To select the Cypher version of a query, prepend it with `CYPHER <language version>`.
173+
This selection will override the default language for the database the query is executed against, and allows you to either work with Cypher 25 features in a database that has Cypher 5 as the default language, or to continue running your Cypher 5 queries on a database that has Cypher 25 as the default language.
174+
175+
Queries run with Cypher 5 will eventually need to be updated to Cypher 25 as support for Cypher 5 will be discontinued in the future (anticipated no earlier than two additional server LTS cycles).
176+
It is, therefore, recommended to set the default language to Cypher 25 and migrate the necessary queries to its supported syntax rather than prepending individual queries with a Cypher version.
177+
178+
.Select the Cypher version for a query
179+
[.tabbed-example]
180+
=====
181+
[.include-with-Cypher-25]
182+
======
183+
184+
.Cypher 25 query on a Neo4j 2025.06+ database with Cypher 5 as default language
185+
[source,cypher]
186+
----
187+
CYPHER 25
188+
MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
189+
SET n = properties(r)
190+
----
191+
192+
======
193+
194+
[.include-with-Cypher-5]
195+
======
196+
197+
.Cypher 5 query on a Neo4j 2025.06+ database with Cypher 25 as default language
198+
[source,cypher]
199+
----
200+
CYPHER 5
201+
MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
202+
SET n = r
203+
----
204+
205+
======
206+
=====
207+
208+
Selecting `CYPHER 25` ensures that the query will be executed using the language as it exists in the version of Neo4j that the database is currently running, provided it is on Neo4j 2025.06 or later.
209+
210+
Selecting `CYPHER 5` ensures that the query will be executed using the language as it existed at the time of the Neo4j 2025.06 release.
211+
Any changes introduced after the 2025.06 release will not affect the query.
212+
213+
[[procedures-and-functions]]
214+
=== Procedures and functions
215+
216+
link:{neo4j-docs-base-uri}/operations-manual/current/procedures[Procedures] and xref:functions/index.adoc[functions] (including built-in and link:{neo4j-docs-base-uri}/apoc/current/[APOC]) are tied to a specific Cypher language version.
217+
Therefore, procedures and functions in Neo4j 2025.06+ and APOC 2025.06+ (both of which have Cypher 5 as their default language) may behave differently depending on what version of Cypher is used.
218+
219+
For example, APOC 2025.06 removed Cypher 25 support of the procedure `apoc.create.uuids()`, meaning it is not available to queries running Cypher 25.
220+
However, it can still be used on APOC 2025.06 if queries are prepended with `CYPHER 5`, or if the database’s default version is set to `CYPHER 5`.
221+
In this case, Neo4j will use APOC and Cypher 5 as they existed at the time of the 2025.06 release.
222+
223+
.Using a procedure removed in Cypher 25 with APOC 2025.06+
224+
[source, cypher]
225+
----
226+
CYPHER 5
227+
CALL apoc.create.uuids(10)
228+
----
229+
230+
[[cypher-selection-with-other-query-options]]
231+
=== Combine Cypher version selection with other query options
232+
233+
It is possible to combine Cypher version selection with other xref:planning-and-tuning/query-tuning.adoc[query options].
234+
The below example selects both the version and the xref:planning-and-tuning/runtimes/concepts.adoc[runtime] of Cypher for the same query:
235+
236+
.Combining Cypher version selection with other query options
237+
[source, cypher]
238+
----
239+
CYPHER 5 runtime=parallel
240+
MATCH (n:Person)
241+
RETURN n.name
242+
----
243+

0 commit comments

Comments
 (0)