Graph reference updates for Cypher 25 / Neo4j 2025.06 #2443
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,12 +9,12 @@ Starting with Neo4j 2025.04, a database alias can also be set as the default dat | |
| //// | ||
| [source, cypher, role=test-setup] | ||
| ---- | ||
| CYPHER 25 CREATE DATABASE `sci-fi-books`; | ||
| CYPHER 25 CREATE COMPOSITE DATABASE `library`; | ||
| CYPHER 25 CREATE ALIAS `library.sci-fi` FOR DATABASE `sci-fi-books`; | ||
| CYPHER 25 CREATE ALIAS `library.romance` FOR DATABASE `romance-books` AT 'neo4j+s://location:7687' USER alice PASSWORD 'password'; | ||
| CYPHER 25 CREATE COMPOSITE DATABASE garden; | ||
| CYPHER 25 CREATE DATABASE `perennial-flowers`; | ||
| ---- | ||
| //// | ||
|
|
||
|
|
@@ -58,7 +58,7 @@ For a description of all the returned columns of this command, and for ways in w | |
|
|
||
| Both local and remote database aliases can be part of a xref::database-administration/composite-databases/concepts.adoc[composite database]. | ||
|
|
||
| The database alias consists of two parts, separated by a dot: the namespace and the alias name. | ||
|
|
||
| The namespace must be the name of the composite database. | ||
|
|
||
|
|
@@ -220,15 +220,175 @@ SHOW DATABASE garden YIELD name, type, constituents | |
| ---- | ||
|
|
||
| [[alias-management-escaping]] | ||
| == Database alias names that contain dots | ||
|
|
||
| Naming database aliases in composite databases follows the same rule as xref:database-administration/aliases/naming-aliases.adoc[naming aliases for standard databases]. | ||
| However, when it comes to escaping names using backticks, there are some additional things to consider: | ||
|
|
||
| Dots in alias names are ambiguous. | ||
| They could either be interpreted as part of the name itself, or as the dot that separates a composite namespace from the alias name. | ||
|
|
||
| [role=label--new-2025.06] | ||
| === Conflicting names | ||
| In versions earlier than Neo4j 2025.06, it is possible to create conflicting aliases, such as the constituent alias `flowers` within the composite database `garden` as well as the non-composite local alias `garden.flowers`. | ||
| Both of these are referred to by the same name, `garden.flowers`. | ||
|
|
||
| Neo4j 2025.06 and later versions ensure that no such conflicts exist and throw an exception when attempting to create a new alias with the same name as an existing alias. | ||
|
|
||
| [.tabbed-example] | ||
| ===== | ||
| [role=include-with-cypher-5] | ||
| ====== | ||
| Creating a regular alias with the same name as an existing composite constituent is disallowed: | ||
|
|
||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 5 CREATE COMPOSITE DATABASE `garden` | ||
| CYPHER 5 CREATE ALIAS `garden`.`flowers` FOR DATABASE `northwind-graph` | ||
| CYPHER 5 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| .Error message | ||
| [source, output, role="noheader"] | ||
| ---- | ||
| Failed to create the specified database alias 'garden.flowers': Database name or alias already exists. | ||
| ---- | ||
| The exception has the GQLSTATUS code link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/42001[42001 - invalid syntax] with the cause link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/42N11[42N11 - graph reference already exists]. | ||
|
|
||
| ====== | ||
|
|
||
| [role=include-with-cypher-25] | ||
| ====== | ||
|
|
||
| Creating a regular alias with the same name as an existing composite constituent is disallowed. | ||
| In Cypher 25, the two names are considered the same since the parts are not quoted separately as they would be in Cypher 5. | ||
|
|
||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 25 CREATE COMPOSITE DATABASE `garden` | ||
| CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph` | ||
| CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph` | ||
|
Comment on lines
+271
to
+272
There was a problem hiding this comment. shouldn't one of these be un escaped to show some difference in the commands? There was a problem hiding this comment. I think this was intentional. As Cypher 25 is going out today, we will merge this PR but feel free to double-check this with Lasse when he is back from vacation There was a problem hiding this comment. Sure, @l-heemann can confirm if that is something we want to update when he gets back :P There was a problem hiding this comment. Yes this is intentional to show the difference between Cypher 5 and 25 (by toggling the tabbed view back and forth) There was a problem hiding this comment. But having both the CYPHER 25 commands be identical feels weird to me... if I did that in Cypher 5 I would fail on it trying to create the same thing twice as well... so why not have one There was a problem hiding this comment. That would be making it less clear by introducing a third variation (unquoted). The whole point of this section is to show that the syntax used to differentiate between composite constituent and regular alias, but now there is no syntactic difference and therefore the error says "these things are the same". I didn't come up with a better way to highlight "no syntactic difference" other than showing the two identical lines next to each other. |
||
| ---- | ||
|
|
||
| .Error message | ||
| [source, output, role="noheader"] | ||
| ---- | ||
| Failed to create the specified database alias 'garden.flowers': Database name or alias already exists. | ||
renetapopova marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ---- | ||
| The exception has the GQLSTATUS code link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/42001[42001 - invalid syntax] with the cause link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/42N11[42N11 - graph reference already exists]. | ||
| ====== | ||
| ===== | ||
|
|
||
| [.tabbed-example] | ||
| ===== | ||
| [role=include-with-cypher-5] | ||
| ====== | ||
| Creating a composite constituent with the same name as an existing non-composite alias is disallowed. | ||
| This example scenario is already prevented on the second line; thus, the constituent on the third line cannot be created. | ||
|
|
||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph` | ||
| CYPHER 5 CREATE COMPOSITE DATABASE `garden` | ||
| CYPHER 5 CREATE ALIAS `garden`.`flowers` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| .Error message | ||
| [source, output, role="noheader"] | ||
| ---- | ||
| Cannot create database 'garden' because another database 'garden.flowers' exists with an ambiguous name. | ||
renetapopova marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ---- | ||
| The exception has the GQLSTATUS code link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/42N87[42N87 - database or alias with similar name exists]. | ||
| ====== | ||
|
|
||
| [role=include-with-cypher-25] | ||
| ====== | ||
|
|
||
| Creating a composite constituent with the same name as an existing non-composite alias is disallowed. | ||
| This example scenario is already prevented on the second line; thus, the constituent on the third line cannot be created. | ||
| The Cypher 25 syntax makes no distinction between the names to clarify that they are considered equivalent. | ||
|
|
||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph` | ||
| CYPHER 25 CREATE COMPOSITE DATABASE `garden` | ||
| CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| .Error message | ||
| [source, output, role="noheader"] | ||
| ---- | ||
| Cannot create database 'garden' because another database 'garden.flowers' exists with an ambiguous name. | ||
| ---- | ||
| The exception has GQLSTATUS code link:{neo4j-docs-base-uri}/status-codes/current/errors/gql-errors/42N87[42N87 - database or alias with similar name exists]. | ||
| ====== | ||
| ===== | ||
|
|
||
|
|
||
|
|
||
| [role=label--new-2025.06] | ||
| === Cypher 25 specific behaviour | ||
l-heemann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ==== Accessing an existing alias with dots | ||
|
|
||
| Cypher 25 relies on the guarantee that no conflicting names are allowed in Neo4j 2025.06 and later. | ||
| The following queries all act on the same alias, regardless of whether that alias is a composite constituent or not. | ||
| The special quoting of separate name parts that is necessary in Cypher 5 is not permitted in Cypher 25. | ||
|
|
||
| .Parameters | ||
| [source, javascript] | ||
| ---- | ||
| { | ||
| "name": "my.garden.beautiful.flowers" | ||
| } | ||
| ---- | ||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 25 ALTER ALIAS `my.garden.beautiful.flowers` SET DATABASE PROPERTIES { perennial: true } | ||
| CYPHER 25 ALTER ALIAS $name SET DATABASE PROPERTIES { perennial: true } | ||
| CYPHER 25 USE `my.garden.beautiful.flowers` RETURN 1 | ||
| ---- | ||
|
|
||
| ==== Creating a new alias with dots | ||
|
|
||
| During `CREATE`, Cypher 25 splits the given name on each dot, left to right, and checks if a corresponding composite database exists. | ||
| If no composite database is found, Cypher 25 falls back to creating a regular non-composite alias. | ||
|
|
||
| For example: | ||
|
|
||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 25 CREATE COMPOSITE DATABASE `my.garden` | ||
| CYPHER 25 CREATE ALIAS `my.garden.beautiful.flowers` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| The query attempts to create the following aliases in the given order: | ||
|
|
||
| . Constituent alias `garden.beautiful.flowers` within composite database `my`. | ||
| . Constituent alias `beautiful.flowers` within composite database `my.garden`. | ||
| . Constituent alias `flowers` within composite database `my.garden.beautiful`. | ||
| . Regular non-composite alias `my.garden.beautiful.flowers`. | ||
|
|
||
| When it finds the composite database `my.garden`, it creates the constituent alias `beautiful.flowers` within that composite. | ||
|
|
||
|
|
||
|
|
||
| === Cypher 5 specific behaviour | ||
|
|
||
| ==== Quoting database alias and composite database names | ||
|
|
||
| The composite database name and the database alias name need to be quoted individually. | ||
| Backticks may be added regardless of whether the name contains special characters or not, so it is good practice to always backtick both names, e.g. `++`composite`++.++`alias`++`. | ||
Lojjs marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| [NOTE] | ||
| ==== | ||
| Separating composite database name and alias name with backticks is no longer supported in Cypher 25. | ||
| See <<_cypher_25_specific_behaviour, Cypher 25 specific behaviour>> for details. | ||
| ==== | ||
|
|
||
| The following example creates a database alias named `my alias with spaces` as a constituent in the composite database named `my-composite-database-with-dashes`: | ||
|
|
||
|
|
@@ -242,18 +402,18 @@ CREATE DATABASE `northwind-graph`; | |
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS `my-composite-database-with-dashes`.`my alias with spaces` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| When not quoted individually, a database alias with the full name `my alias with.dots and spaces` gets created instead: | ||
|
|
||
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| ==== Handling multiple dots | ||
|
|
||
| //Examples where dots are not separators between composite name and alias name are impossible to test, because the right escaping cannot be inferred automatically. | ||
|
|
||
|
|
@@ -263,18 +423,20 @@ Though these always need to be quoted in order to avoid ambiguity with the compo | |
| .Query | ||
| [source, cypher, role=test-skip] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| .Query | ||
| [source, cypher, role=test-skip] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| ==== Single dots and local database aliases | ||
| [NOTE] | ||
l-heemann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ==== | ||
| As of Neo4j 2025.06, this feature is no longer deprecated. | ||
renetapopova marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ==== | ||
|
|
||
| There is a special case for local database aliases with a single dot without any existing composite database. | ||
| If a composite database `some` exists, the query below will create a database alias named `alias` within the composite database `some`. | ||
|
|
@@ -283,10 +445,10 @@ If no such database exists, however, the same query will instead create a databa | |
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS some.alias FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| ==== Handling parameters | ||
|
|
||
| When using parameters, names cannot be quoted. | ||
| When the given parameter includes dots, the first dot will be considered the divider for the composite database. | ||
|
|
@@ -304,7 +466,7 @@ Consider the query with parameter: | |
| .Query | ||
| [source, cypher] | ||
| ---- | ||
| CYPHER 5 CREATE ALIAS $aliasname FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| If the composite database `mysimplecompositedatabase` exists, then a database alias `myalias` will be created in that composite database. | ||
|
|
@@ -326,7 +488,7 @@ If `mycompositedatabase` does not exist, the command will create a database alia | |
|
|
||
| In these cases, it is recommended to avoid parameters and explicitly quote the composite database name and alias name separately to avoid ambiguity. | ||
|
|
||
| ==== Handling parameters | ||
|
|
||
| Further special handling with parameters is needed for database aliases and similarly named composite databases. | ||
|
|
||
|
|
@@ -335,8 +497,8 @@ Consider the setup: | |
| .Query | ||
| [source, cypher, role="noheader test-skip"] | ||
| ---- | ||
| CYPHER 5 CREATE COMPOSITE DATABASE foo | ||
| CYPHER 5 CREATE ALIAS `foo.bar` FOR DATABASE `northwind-graph` | ||
| ---- | ||
|
|
||
| The alias `foo.bar` does not belong to the composite database `foo`. | ||
|
|
@@ -354,7 +516,7 @@ Dropping this alias using parameters fails with an error about a missing alias: | |
| .Query | ||
| [source, cypher, role=test-fail] | ||
| ---- | ||
| CYPHER 5 DROP ALIAS $aliasname FOR DATABASE | ||
| ---- | ||
|
|
||
| .Error message | ||
|
|
||
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
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.