Select Cypher version

modules/ROOT/content-nav.adoc

@@ -6,6 +6,7 @@
 * xref:queries/index.adoc[]
 ** xref:queries/concepts.adoc[]
 ** xref:queries/basic.adoc[]
+** xref:queries/select-version.adoc[]
 ** xref:queries/composed-queries/index.adoc[]
 *** xref:queries/composed-queries/combined-queries.adoc[]
 *** xref:queries/composed-queries/conditional-queries.adoc[]

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

@@ -1,5 +1,5 @@
 [[cypher-deprecations-additions-removals-compatibility]]
-= Deprecations, additions, and compatibility
+= Additions, deprecations, removals, and compatibility
 :description: all of the features that have been removed, deprecated, added, or extended in different Cypher versions.
 :test-skip: true  // all deprecations would fail.
 

modules/ROOT/pages/queries/index.adoc

@@ -6,6 +6,7 @@ It also discusses how to compose combined queries using `UNION` and conditional
 
 * xref:queries/concepts.adoc[]
 * xref:queries/basic.adoc[]
+* xref:queries/select-version.adoc[]
 * xref:queries/composed-queries/index.adoc[]
 ** xref:queries/composed-queries/combined-queries.adoc[]
 ** xref:queries/composed-queries/conditional-queries.adoc[] label:new[Introduced in Neo4j 2025.06]

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

@@ -0,0 +1,245 @@
+:description: Information about how to select Cypher version for queries or databases.
+
+= Select Cypher version
+
+Users can specify the version of Cypher in which they want to run their queries, choosing between Cypher 5 and Cypher 25.
+The Cypher version can be specified either by configuring a default language for the database or by setting it on a per-query basis.
+
+[[cypher-versions-explained]]
+== Cypher 25, Cypher 5, and Neo4j explained
+
+Starting in 2025, the Neo4j server transitioned to a calendar-based versioning system.
+This means Neo4j will no longer use its previous semantic versioning and release pattern (e.g., 5.25, 5.26).
+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.
+
+Cypher 25 is introduced alongside *Neo4j 2025.06*.
+It is created as a clone of Cypher 5, but with additional new and updated features, as well as some removed features.
+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.
+
+Cypher 25 is in a evolving state, and more features will be added to it with future releases of Neo4j.
+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.
+*Any new Cypher features introduced in Neo4j 2025.06 or later will be exclusively added to Cypher 25.*
+
+Users running Neo4j version 2025.06 or later can choose to run their queries using the previous version of Cypher: Cypher 5.
+If so, Neo4j will use Cypher as it existed at the time of the Neo4j 2025.05 release, the release in which Cypher 5 was frozen.
+*No new features will be added to Cypher 5.*
+For information about Cypher 5, see the link:https://neo4j.com/docs/cypher-manual/5/introduction/[Cypher 5 Manual].
+
+[NOTE]
+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).
+
+[[select-default-cypher-version]]
+== Select the default Cypher version for a database
+
+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`).
+This is true for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/#manage-database-systems[system, standard, and composite] Neo4j databases.
+However, it is possible to set a different default language on both new and existing system, standard, and composite databases.
+
+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.
+
+[NOTE]
+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].
+
+.Select default Cypher version when creating a database
+[.tabbed-example]
+=====
+[.include-with-Cypher-25]
+======
+
+.Cypher 25
+[source,cypher]
+----
+CREATE DATABASE my_new_database DEFAULT LANGUAGE CYPHER 25
+----
+
+======
+
+[.include-with-Cypher-5]
+======
+
+.Cypher 5
+[source,cypher]
+----
+CREATE DATABASE my_database DEFAULT LANGUAGE CYPHER 5
+----
+
+======
+=====
+
+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.
+
+[NOTE]
+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].
+
+.Alter the default Cypher version on an existing database
+[.tabbed-example]
+=====
+[.include-with-Cypher-25]
+======
+
+.Cypher 25
+[source,cypher]
+----
+ALTER DATABASE my_database SET DEFAULT LANGUAGE CYPHER 25
+----
+
+======
+
+[.include-with-Cypher-5]
+======
+
+.Cypher 5
+[source,cypher]
+----
+ALTER DATABASE my_new_database SET DEFAULT LANGUAGE CYPHER 5
+----
+
+======
+=====
+
+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 `CYPHER 5`, which overrides this default).
+
+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.05 release (unless a query is prepended with `CYPHER 25`, which overrides this default).
+Any changes introduced after the 2025.05 release will not affect the semantics of the query.
+
+For information about how to set a default language for local and remote database aliases, see link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/aliases/manage-aliases-standard-databases/[The Operations Manual -> Managing database aliases for standard databases] and link:{neo4j-docs-base-uri}/operations-manual/current/database-administration//aliases/manage-aliases-composite-databases/[Managing database aliases in composite databases].
+
+
+[[config-database-upgrades]]
+== Cypher versions, configuration settings, and DBMS upgrades
+
+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`).
+This setting determines the default language for new databases where it has not been specified as part of a `CREATE` or `ALTER` database command.
+For example, `config_db.query.default_language=CYPHER_25` will set Cypher 25 as the default language for a DBMS.
+For more information about using configuration settings, see the link:{neo4j-docs-base-uri}/operations-manual/current/configuration/[Operations Manual -> Configuration].
+
+The table below outlines which Cypher version is assigned to databases in different upgrade or installation scenarios:
+
+[cols="3", options="header"]
+|===
+| Scenario | `db.query.default_language` | Databases
+
+
+| *Standard DBMS upgrade to Neo4j 2025.06+*
+| Unset
+| *Existing system database:* `CYPHER 5` +
+*Existing user databases:* `CYPHER 5` +
+*New user databases default:* `CYPHER 5`
+
+
+| *Custom DBMS upgrade to Neo4j 2025.06+*
+| Manually set to `CYPHER_25` by administrator
+| *Existing system database:* `CYPHER 5` +
+*Existing user databases:* `CYPHER 5`  +
+*New user databases default:* `CYPHER 25`
+
+
+| *New installation of Neo4j 2025.06+*
+| Set to `CYPHER_5`
+| *New system database:* `CYPHER 5` +
+*New user databases default:* `CYPHER 5`
+
+
+|===
+
+For more information about upgrading and migrating Neo4j databases, see the link:{neo4j-docs-base-uri}/upgrade-migration-guide/current/[Upgrade and migration guide].
+
+[[migrate-queries-from-5-to-25]]
+== Migrating queries from Cypher 5 to Cypher 25
+
+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.
+
+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.
+The following example demonstrates how a query that works in Cypher 5 can be rewritten to work in Cypher 25.
+
+.Original Cypher 5 query
+[source, cypher]
+----
+MATCH (n:Order)-[r:SHIPPED_TO]->(:Address) 
+SET n = r
+----
+
+.Modified Cypher 25 query
+[source, cypher]
+----
+MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
+SET n = properties(r)
+----
+
+Another option is to prepend individual queries with a specific language version.
+
+[[selection-query-cypher-version]]
+== Select Cypher version for individual queries
+
+To select the Cypher version of a query, prepend it with `CYPHER <language version>`.
+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.
+
+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).
+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.
+
+.Select the Cypher version for a query
+[.tabbed-example]
+=====
+[.include-with-Cypher-25]
+======
+
+.Cypher 25 query on a Neo4j 2025.06+ database with Cypher 5 as default language
+[source,cypher]
+----
+CYPHER 25
+MATCH (n:Order)-[r:SHIPPED_TO]->(:Address)
+SET n = properties(r)
+----
+
+======
+
+[.include-with-Cypher-5]
+======
+
+.Cypher 5 query on a Neo4j 2025.06+ database with Cypher 25 as default language
+[source,cypher]
+----
+CYPHER 5
+MATCH (n:Order)-[r:SHIPPED_TO]->(:Address) 
+SET n = r
+----
+
+======
+=====
+
+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.
+
+Selecting `CYPHER 5` ensures that the query will be executed using the language as it existed at the time of the Neo4j 2025.05 release.
+Any changes introduced after the 2025.05 release will not affect the query.
+
+[[procedures-and-functions]]
+=== Procedures and functions
+
+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.
+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.
+
+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.
+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`.
+In this case, Neo4j will use APOC and Cypher as they existed at the time of the 2025.05 release.
+
+.Using a procedure removed in Cypher 25 with APOC 2025.06+
+[source, cypher]
+----
+CYPHER 5
+CALL apoc.create.uuids(10)
+----
+
+[[cypher-selection-with-other-query-options]]
+=== Combine Cypher version selection with other query options
+
+It is possible to combine Cypher version selection with other xref:planning-and-tuning/query-tuning.adoc[query options].
+The below example selects both the version and the xref:planning-and-tuning/runtimes/concepts.adoc[runtime] of Cypher for the same query:
+
+.Combining Cypher version selection with other query options
+[source, cypher]
+----
+CYPHER 5 runtime=parallel
+MATCH (n:Person)
+RETURN n.name
+----
+