Skip to content

Errors and deprecations for graph references #340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: dev
Choose a base branch
from
+214 −1
Open

Errors and deprecations for graph references #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2fdcf34
Document new GQLSTATUS codes 51N76 and 42NAA
Lojjs Jun 9, 2025
5108026
Document changes to graph reference deprecations.
Lojjs Jun 10, 2025
42b58bc
Improve 42NAA docs:
Lojjs Jun 16, 2025
8c744be
Update links to point at Cypher 25 docs for graph references (to be p…
Lojjs Jun 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions modules/ROOT/content-nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,7 @@
**** xref:errors/gql-errors/42NA7.adoc[]
**** xref:errors/gql-errors/42NA8.adoc[]
**** xref:errors/gql-errors/42NA9.adoc[]
**** xref:errors/gql-errors/42NAA.adoc[]
**** xref:errors/gql-errors/42NFC.adoc[]
**** xref:errors/gql-errors/42NFD.adoc[]
**** xref:errors/gql-errors/42NFE.adoc[]
Expand Down Expand Up @@ -452,6 +453,7 @@
**** xref:errors/gql-errors/51N72.adoc[]
**** xref:errors/gql-errors/51N73.adoc[]
**** xref:errors/gql-errors/51N74.adoc[]
**** xref:errors/gql-errors/51N76.adoc[]
*** xref:errors/gql-errors/index.adoc#procedure-exceptions[Procedure exceptions]
**** xref:errors/gql-errors/52N01.adoc[]
**** xref:errors/gql-errors/52N02.adoc[]
Expand Down
61 changes: 61 additions & 0 deletions modules/ROOT/pages/errors/gql-errors/42NAA.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
= 42NAA

== Status description
error: syntax error or access rule violation - incorrectly formatted graph reference. Incorrectly formatted graph reference `{ <<input>> }`. Expected a single quoted or unquoted identifier. Separate name parts should not be quoted individually.

== Explanation
As of Cypher 25, database names and aliases cannot include name parts that are quoted individually.
Either the whole name must be quoted, or the whole name must be unquoted.
A recommended approach, which is consistent between different commands and Cypher versions, is to send in the database name or alias as a parameter rather than a string literal.

== Example scenario
For example, try to create a database with

[source,cypher]
----
CYPHER 25 CREATE ALIAS `foo`.`bar` FOR DATABASE baz
----

An error will be thrown with GQLSTATUS 42NAA and the status description

[source]
----
error: syntax error or access rule violation - incorrectly formatted graph reference. Incorrectly formatted graph reference '`foo`.`bar`'. Expected a single quoted or unquoted identifier. Separate name parts should not be quoted individually.
----

In this example scenario, the preferred way is to send in the alias name as a parameter

.Parameters
[source, parameters]
----
{
"aliasName": "foo.bar"
}
----

.Query
[source, cypher]
----
CREATE ALIAS $aliasName FOR DATABASE baz
----

Alternatively, if a string literal is used, the correct quoting for Cypher 25 would either be

[source,cypher]
----
CYPHER 25 CREATE ALIAS `foo.bar` FOR DATABASE baz
----

or

[source,cypher]
----
CYPHER 25 CREATE ALIAS foo.bar FOR DATABASE baz
----

ifndef::backend-pdf[]
[discrete.glossary]
== Glossary

include::partial$glossary.adoc[]
endif::[]
16 changes: 16 additions & 0 deletions modules/ROOT/pages/errors/gql-errors/51N76.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
= 51N76


== Status description
error: system configuration or operation exception - upgrade failed. The upgrade to a new Neo4j version failed.

== Explanation
This error code can occur during a dbms upgrade to a new Neo4j version, in the rare case that something in the user's setup or dbms environment prevented the dbms from upgrading.
The error will be accompanied by a cause with a more concrete GQLSTATUS, describing what the user needs to change before retrying the upgrade.

ifndef::backend-pdf[]
[discrete.glossary]
== Glossary

include::partial$glossary.adoc[]
endif::[]
136 changes: 135 additions & 1 deletion modules/ROOT/pages/notifications/all-notifications.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1246,8 +1246,10 @@ To continue using it, escape the identifier by adding backticks around the ident
To continue using it, escape the identifier by adding backticks around the identifier `%s`.
- label:new[Valid for Neo4j 5.5-5.25] All subqueries in a UNION [ALL] should have the same ordering for the return columns.
Using differently ordered return items in a UNION [ALL] clause is deprecated and will be removed in a future version.
- Databases and aliases with unescaped `.` are deprecated unless to indicate that they belong to a composite database.
- label:new[Valid for Neo4j 5.26-2025.05] Databases and aliases with unescaped `.` are deprecated unless to indicate that they belong to a composite database.
Copy link
Contributor Author

@Lojjs Lojjs Jun 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reused the format of the label from the entry above, but that is not visible in the published docs of some reason

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand this label? What do we mean by "valid" here? I almost feel like we need a "incorrectly deprecated" flag...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can discuss this comment together with @renetapopova later in the week (Lasse is out today) as I just copied it from an already existing similar place

Names containing `.` should be escaped. (`%s`)
- label:new[Valid from 2025.06] Graph references with separately backticked name parts (`%s`) are deprecated. In future Cypher versions, use parameters or backtick the entire name (`%s`).
- label:new[Valid from 2025.06] Graph references with separately backticked name parts (`%s`) are deprecated. In future Cypher versions, remove the backticks (`%s`).
|Category
m|DEPRECATION
|GQLSTATUS code
Expand All @@ -1260,6 +1262,124 @@ m|DEPRECATION
m|WARNING
|===

[#_graph_reference_deprecation]
.Using separately backticked name parts in graph references
[.tabbed-example]
=====
[.include-with-GQLSTATUS-code]
======
Query::
+
[source,cypher]
----
CYPHER 5 CREATE ALIAS `foo`.`bar` FOR DATABASE ...
----

Returned GQLSTATUS code::
01N00

Returned status description::
warn: feature deprecated.
Graph references with separately backticked name parts (\`foo`.\`bar`) are deprecated. In future Cypher versions, use parameters or backtick the entire name (\`foo.bar`).

Suggestions for improvement::
In newer Cypher versions, either the whole graph reference name should be backticked or it should be sent in as a parameter.
+
[source,cypher]
----
CYPHER 25 CREATE ALIAS `foo.bar` FOR DATABASE ...
----
+
[source,cypher]
----
CYPHER 25 CREATE ALIAS $param FOR DATABASE ...
----
For more information on the semantics of graph references, see link:https://neo4j.com/docs/cypher-manual/25/values-and-types/graph-references[Cypher manual -> Graph references].

======
[.include-with-neo4j-code]
======
Query::
+
[source,cypher]
----
CYPHER 5 CREATE ALIAS `foo`.`bar` FOR DATABASE ...
----

Description of the returned code::
Graph references with separately backticked name parts (\`foo`.\`bar`) are deprecated. In future Cypher versions, use parameters or backtick the entire name (\`foo.bar`).

Suggestions for improvement::
In newer Cypher versions, either the whole graph reference name should be backticked or it should be sent in as a parameter.
+
[source,cypher]
----
CYPHER 25 CREATE ALIAS `foo.bar` FOR DATABASE ...
----
+
[source,cypher]
----
CYPHER 25 CREATE ALIAS $param FOR DATABASE ...
----
For more information on the semantics of graph references, see link:https://neo4j.com/docs/cypher-manual/25/values-and-types/graph-references[Cypher manual -> Graph references].

======
=====

[#_graph_reference_deprecation_use]
.Using separately backticked name parts in graph references in USE clause
[.tabbed-example]
=====
[.include-with-GQLSTATUS-code]
======
Query::
+
[source,cypher]
----
CYPHER 5 USE graph.byName("`a.b`.c") ...
----

Returned GQLSTATUS code::
01N00

Returned status description::
warn: feature deprecated.
Graph references with separately backticked name parts (\`a.b`.\`c`) are deprecated. In future Cypher versions, remove the backticks (a.b.c).

Suggestions for improvement::
In newer Cypher versions, the backticks should be removed.
+
[source,cypher]
----
CYPHER 25 USE graph.byName("a.b.c") ...
----
For more information on the semantics of graph references, see link:https://neo4j.com/docs/cypher-manual/25/values-and-types/graph-references[Cypher manual -> Graph references].

======
[.include-with-neo4j-code]
======
Query::
+
[source,cypher]
----
CYPHER 5 USE graph.byName("`a.b`.c") ...
----

Description of the returned code::
Graph references with separately backticked name parts (\`a.b`.\`c`) are deprecated. In future Cypher versions, remove the backticks (a.b.c).

Suggestions for improvement::
In newer Cypher versions, the backticks should be removed.
+
[source,cypher]
----
CYPHER 25 USE graph.byName("a.b.c") ...
----
For more information on the semantics of graph references, see link:https://neo4j.com/docs/cypher-manual/25/values-and-types/graph-references[Cypher manual -> Graph references].

======
=====

.Create a database with an unescaped name containing a dot
[.tabbed-example]
=====
Expand Down Expand Up @@ -1311,6 +1431,20 @@ CREATE DATABASE `foo.bar`
======
=====

[NOTE]
====
Databases and aliases with unescaped `.` are deprecated in versions 5.26 to 2025.05.
However, starting from version 2025.06, this deprecation has been withdrawn, and replaced by two new deprecations.
The reason for this change is that the previous quoting rules have been found inconsistent and ambiguous, and will be improved starting from Cypher 25.
For more information, see:

<<_graph_reference_deprecation>>

<<_graph_reference_deprecation_use>>
Comment on lines +1441 to +1443
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These links seem to not work either, even though they are to the same page 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting, I can see they do not work in the preview on the PR, however they do work in the Intellij ascii doc preview. Perhaps someone from docs team can figure out what I have done wrongly...


link:https://neo4j.com/docs/cypher-manual/25/values-and-types/graph-references[Cypher manual -> Graph references].
====

.Using differently ordered return items in a `UNION` clause
[.tabbed-example]
=====
Expand Down