Skip to content

Commit 8514b29

Browse files
JPryce-AklundhJPryce-Aklundh
committed
write cypher selection page
1 parent af6ea30 commit 8514b29

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
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/expressions.adoc[]
1011
** xref:queries/case.adoc[]
1112

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

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
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 set for individual queries or as the default language for a database.
7+
8+
== Cypher 5, Cypher 25, and Neo4j explained
9+
10+
Starting in 2025, the Neo4j server transitioned to a calendar-based versioning system.
11+
This means Neo4j will no longer use its previous semantic versioning and release pattern (e.g., 5.25, 5.26).
12+
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.
13+
14+
Cypher 25 is introduced alongside Neo4j 2025.01 and is the default language for databases running version 2025.01 later.
15+
However, users running Neo4j version 2025.01 or later can choose to run their queries using the previous version of Cypher: Cypher 5.
16+
If so, Neo4j will use Cypher as it existed at the time of the Neo4j 5.26 long-term support release.
17+
18+
For information about updates to Cypher in different Neo4j versions, see xref:deprecations-additions-removals-compatibility.adoc[].
19+
For information about Cypher 5, see the link:https://neo4j.com/docs/cypher-manual/5/introduction/[Cypher 5 Manual].
20+
21+
== Select the Cypher version for queries
22+
23+
To select the Cypher version of a query, prepend it with `CYPHER <language version>`.
24+
25+
Selecting `CYPHER 5` ensures that the query will be executed using the language as it existed at the time of the Neo4j 5.26 long-term support release.
26+
Any changes introduced in Neo4j 2025.01 or later will not affect the query.
27+
28+
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.01 or later.
29+
30+
Below are two examples showing the two versions of Cypher behaving differently.
31+
32+
.Differences in setting properties between Cypher 5 and Cypher 25
33+
======
34+
The first query uses a `RELATIONSHIP` instead of `MAP` on the right-hand side of a xref:clauses/set.adoc[`SET`] clause.
35+
This was allowed in Cypher 5, but disallowed in Cypher 25, which requires that the xref:functions/scalar.adoc#functions-properties[`properties()`] function is used to get the map of properties from nodes or relationships before referencing them in a `SET` clause.
36+
37+
.Setting properties on a node from a relationship using Cypher 5
38+
[source, cypher]
39+
----
40+
CYPHER 5
41+
MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
42+
SET n = r
43+
----
44+
45+
.Setting properties on a node from a relationship using Cypher 25
46+
[source, cypher]
47+
----
48+
CYPHER 25
49+
MATCH (n:Order)-[r:SHIPPED_TO]->(m:Address)
50+
SET n = properties(r)
51+
----
52+
======
53+
54+
.Differences in listing constraints between Cypher 5 and Cypher 25
55+
======
56+
In this example, the same statement listing the `name` and `type` of the xref:constraints/index.adoc[constraints] in a database is executed first using Cypher 5 and then with Cypher 25.
57+
Note that the return values in the `type` column have been updated in the results from the statement run with Cypher 25.
58+
59+
////
60+
CREATE CONSTRAINT node_uniqueness_constraint
61+
FOR (n:Label) REQUIRE n.property IS UNIQUE;
62+
CREATE CONSTRAINT rel_uniqueness_constraint
63+
FOR ()-[r:REL_TYPE]-() REQUIRE r.property IS UNIQUE;
64+
////
65+
66+
.Listing the constraint name and type values using Cypher 5
67+
[source, cypher]
68+
----
69+
CYPHER 5
70+
SHOW CONSTRAINTS YIELD name, type
71+
----
72+
73+
.Result
74+
[source, queryresult]
75+
----
76+
+----------------------------------------------------------+
77+
| name | type |
78+
+----------------------------------------------------------+
79+
| "node_uniqueness_constraint" | "UNIQUENESS" |
80+
| "rel_uniqueness_constraint" | "RELATIONSHIP_UNIQUENESS" |
81+
+----------------------------------------------------------+
82+
----
83+
84+
.Listing the constraint name and type values using Cypher 25
85+
[source, cypher]
86+
----
87+
CYPHER 5
88+
SHOW CONSTRAINTS YIELD name, type
89+
----
90+
91+
.Result
92+
[source, queryresult]
93+
----
94+
+-------------------------------------------------------------------+
95+
| name | type |
96+
+-------------------------------------------------------------------+
97+
| "node_uniqueness_constraint" | "NODE_PROPERTY_UNIQUENESS" |
98+
| "rel_uniqueness_constraint" | "RELATIONSHIP_PROPERTY_UNIQUENESS" |
99+
+-------------------------------------------------------------------+
100+
----
101+
102+
======
103+
104+
If a database has specified a default Cypher version, it is possible to set a different Cypher version for individual queries.
105+
For example, if a database is created with Cypher 5 as its default language, prepending a query run on that database with `CYPHER 25` ensures the query uses Cypher 25.
106+
107+
=== Combine Cypher version selection with other query options
108+
109+
It is possible to combine Cypher version selection with other xref:planning-and-tuning/query-tuning.adoc[query options].
110+
The below example selects both the version and the xref:planning-and-tuning/runtimes/concepts.adoc[runtime] of Cypher for the same query:
111+
112+
.Combining Cypher version selection with other query options
113+
[source, cypher]
114+
----
115+
CYPHER 5 runtime=parallel
116+
MATCH (n:Person)
117+
RETURN n.name
118+
----
119+
120+
== Select the default Cypher version when creating a database
121+
122+
Databases created on Neo4j 2025.01 or later will have Cypher 25 as their default language.
123+
This is true for the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/#manage-database-systems[system, standard, and composite] Neo4j databases.
124+
125+
To select a different default Cypher version for a database, add `DEFAULT LANGUAGE <language version>` to the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/create-databases/[`CREATE DATABASE`] statement.
126+
This can be done on any Neo4j database.
127+
128+
[NOTE]
129+
Selecting a default Cypher version on a database requires the `SET DEFAULT LANGUAGE` privilege.
130+
131+
Selecting `CYPHER 5` as the default database language ensures that every query run on that database uses the language as it existed at the time of the Neo4j 5.26 long-term support release.
132+
Any changes introduced in Neo4j 2025.01 or later will not affect the query.
133+
134+
.Create a database with Cypher 5 as the default language
135+
[source, cypher]
136+
----
137+
CREATE DATABASE my_database DEFAULT LANGUAGE CYPHER 5
138+
----
139+
140+
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.01 or later.
141+
142+
.Create a database with Cypher 25 as the default language
143+
[source, cypher]
144+
----
145+
CREATE DATABASE my_new_database DEFAULT LANGUAGE CYPHER 25
146+
----
147+
148+
== Alter the default Cypher version for a database
149+
150+
To alter the default Cypher version on a database, add `SET DEFAULT LANGUAGE <language version>` to the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/alter-databases/[`ALTER DATABASE`] command.
151+
152+
[NOTE]
153+
Selecting a default Cypher version on a database requires the `SET DEFAULT LANGUAGE` privilege.
154+
155+
.Set Cypher 5 as the default language on an existing database
156+
[source, cypher]
157+
----
158+
ALTER DATABASE my_new_database SET DEFAULT LANGUAGE CYPHER 5
159+
----
160+
161+
.Set Cypher 25 as the default language on an existing database
162+
[source, cypher]
163+
----
164+
ALTER DATABASE my_database SET DEFAULT LANGUAGE CYPHER 25
165+
----
166+
167+
== Show the Cypher version of databases
168+
169+
The Cypher version of a database can be seen using the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/listing-databases/[`SHOW DATABASES`] command as follows:
170+
171+
.Set Cypher 25 as the default language on an existing database
172+
[source, cypher]
173+
----
174+
SHOW DATABASES YIELD name, defaultLanguage
175+
----
176+
177+
.Result
178+
[source, queryresult]
179+
----
180+
+-----------------------------------------+
181+
| name | defaultLanguage |
182+
+-----------------------------------------+
183+
| "my_database" | "CYPHER 25" |
184+
| "my_new_database" | "CYPHER 5" |
185+
| "system" | "CYPHER 25" |
186+
+-----------------------------------------+
187+
----

0 commit comments

Comments
 (0)