Select Cypher version #1123
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,243 @@ | ||||||
| :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 an 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 5 as it existed at the time of the Neo4j 2025.06 release (the release in which Cypher 5 was frozen). | ||||||
| *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). | ||||||
| Cypher 5 users must, therefore, migrate to Cypher 25 in order to access new features. | ||||||
| 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]. | ||||||
|
There was a problem hiding this comment. This only applies for the ALTER DATABASE command. For CREATE DATABASE and CREATE COMPOSITE DATABASE commands only the CREATE DATABASE/CREATE COMPOSITE DATABASE privileges are needed. There was a problem hiding this comment. might not need the note at all since it should only say that to create you need privilege to create, which isn't anything new, in difference to that alter case that has new/separate privileges 🤷 |
||||||
|
|
||||||
| .Select default Cypher version when creating a database | ||||||
| [.tabbed-example] | ||||||
| ===== | ||||||
| [.include-with-Cypher-25] | ||||||
| ====== | ||||||
|
|
||||||
| .Cypher 25 | ||||||
| [source,cypher] | ||||||
| ---- | ||||||
| CREATE DATABASE actors DEFAULT LANGUAGE CYPHER 25 | ||||||
|
There was a problem hiding this comment.
Suggested change
This is optional, I prefer having the SET 🤷 SET was added as an optional keyword in the Cypher 25 version of CREATE DATABASE (for all sub-clauses) and isn't available in Cypher 5 |
||||||
| ---- | ||||||
|
|
||||||
| ====== | ||||||
|
|
||||||
| [.include-with-Cypher-5] | ||||||
| ====== | ||||||
|
|
||||||
| .Cypher 5 | ||||||
| [source,cypher] | ||||||
| ---- | ||||||
| CREATE DATABASE movies 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]. | ||||||
|
There was a problem hiding this comment. This only applies for standard and system database, for composite databases you'll need the ALTER COMPOSITE DATABASE privilege instead (it doesn't have a lower level privilege like the standard database case does). |
||||||
|
|
||||||
| .Alter the default Cypher version on an existing database | ||||||
| [.tabbed-example] | ||||||
| ===== | ||||||
| [.include-with-Cypher-25] | ||||||
| ====== | ||||||
|
|
||||||
| .Cypher 25 | ||||||
| [source,cypher] | ||||||
| ---- | ||||||
| ALTER DATABASE movies SET DEFAULT LANGUAGE CYPHER 25 | ||||||
| ---- | ||||||
|
|
||||||
| ====== | ||||||
|
|
||||||
| [.include-with-Cypher-5] | ||||||
| ====== | ||||||
|
|
||||||
| .Cypher 5 | ||||||
| [source,cypher] | ||||||
| ---- | ||||||
| ALTER DATABASE actors 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 xref:selection-query-cypher-version[`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.06 release (unless a query is prepended with xref:selection-query-cypher-version[`CYPHER 25`], which overrides this default). | ||||||
| Any changes introduced after the 2025.06 release will not affect the semantics of the query. | ||||||
|
|
||||||
| [[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, role=test-skip] | ||||||
| ---- | ||||||
| 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). | ||||||
|
There was a problem hiding this comment. As above, time horizon. |
||||||
| 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.06 release. | ||||||
| Any changes introduced after the 2025.06 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 5 as they existed at the time of the 2025.06 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 | ||||||
| ---- | ||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we give a time horizon for when Cypher 5 will be discontinued? Or at least a no earlier than? As we say people are going to have to migrate eventually, it's useful for customers to know by when they need to allocate work to make it happen.