Errors and deprecations for graph references (#340)

The errors have already been merged. The deprecations come from
neo-technology/neo4j#31541

---------

Co-authored-by: Reneta Popova <[email protected]>

Author: Lojjs

modules/ROOT/content-nav.adoc

@@ -356,6 +356,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[]
@@ -454,6 +455,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[]

modules/ROOT/pages/errors/gql-errors/42NAA.adoc

@@ -0,0 +1,63 @@
+= 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 using the following Cypher 25 command:
+
+[source,cypher]
+----
+CYPHER 25 CREATE ALIAS `foo`.`bar` FOR DATABASE baz
+----
+
+An error will be thrown with GQLSTATUS 42NAA and the following 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.
+----
+
+== Possible solutions
+
+To resolve this issue, the preferred way is to replace the alias name with a parameter:
+
+.Parameters
+[source, parameters]
+----
+{
+  "aliasName": "foo.bar"
+}
+----
+
+.Query
+[source, cypher]
+----
+CREATE ALIAS $aliasName FOR DATABASE baz
+----
+
+Alternatively, if you use a string literal, the correct quoting for Cypher 25 will 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::[]

modules/ROOT/pages/errors/gql-errors/51N76.adoc

@@ -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 Neo4j upgrade to a new version in the rare case when something in the user's setup or DBMS environment prevents the upgrade.
+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::[]

modules/ROOT/pages/errors/gql-errors/index.adoc

@@ -1446,6 +1446,10 @@ Status description:: error: syntax error or access rule violation - invalid refe
 
 Status description:: error: syntax error or access rule violation - system database procedure rules. The system database supports a restricted set of Cypher clauses. The supported clause structure for procedure calls is: `CALL`, `YIELD`, `RETURN`. `YIELD` and `RETURN` clauses are optional. The order of the clauses is fixed and each can only occur once.
 
+=== xref:errors/gql-errors/42NAA.adoc[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.
+
 === xref:errors/gql-errors/42NFC.adoc[42NFC]
 
 Status description:: error: syntax error or access rule violation - auth info validation error. Authentication and/or authorization could not be validated. See security logs for details.
@@ -1846,6 +1850,10 @@ Status description:: error: system configuration or operation exception - transa
 
 Status description:: error: system configuration or operation exception - maximum number of transactions reached. Failed to start a new transaction. The limit of concurrent transactions is reached. Increase the number of concurrent transactions using `{ <<cfgSetting>> }` in the neo4j.conf file.
 
+=== xref:errors/gql-errors/51N76.adoc[51N76]
+
+Status description:: error: system configuration or operation exception - upgrade failed. The upgrade to a new Neo4j version failed.
+
 
 [[procedure-exceptions]]
 == Procedure exceptions

modules/ROOT/pages/notifications/all-notifications.adoc

@@ -1244,10 +1244,23 @@ a|
 To continue using it, escape the identifier by adding backticks around the identifier `%s`.
 - The character with the Unicode representation `%s` is deprecated for unescaped identifiers and will not be supported in the future.
 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.
+- All subqueries in a `UNION [ALL]` should have the same ordering for the return columns.
+[NOTE]
+In versions 5.5 to 5.25, using differently ordered return items in a `UNION [ALL]` clause is deprecated.
+However, starting from version 5.26, the deprecation has been withdrawn following cost-benefit analysis and valuable user feedback.
+- label:deprecated[Deprecated from 5.26 to 2025.05] Databases and aliases with unescaped `.` are deprecated unless the dots indicate that they belong to a composite database.
 Names containing `.` should be escaped. (`%s`)
+[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,Using separately backticked name parts in graph references>>
+* <<_graph_reference_deprecation_use,Using separately backticked name parts in graph references in USE clause>>
+* link:https://neo4j.com/docs/cypher-manual/25/values-and-types/graph-references[Cypher manual -> Graph references].
+- label:deprecated[Deprecated in 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:deprecated[Deprecated in 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
@@ -1260,6 +1273,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]
 =====
@@ -1311,6 +1442,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,Using separately backticked name parts in graph references>>
+
+* <<_graph_reference_deprecation_use,Using separately backticked name parts in graph references in USE clause>>
+
+* 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]
 =====
@@ -1373,7 +1518,7 @@ RETURN 'val' as one, 'val' as two
 
 [NOTE]
 ====
-Using differently ordered return items in a UNION [ALL] clause is deprecated in versions 5.5 to 5.25.
+In versions 5.5 to 5.25, using differently ordered return items in a `UNION [ALL]` clause is deprecated.
 However, starting from version 5.26, the deprecation has been withdrawn following cost-benefit analysis and valuable user feedback.
 ====