diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 78adb891..78d96bfc 100644 --- a/modules/ROOT/content-nav.adoc +++ b/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[] diff --git a/modules/ROOT/pages/errors/gql-errors/42NAA.adoc b/modules/ROOT/pages/errors/gql-errors/42NAA.adoc new file mode 100644 index 00000000..9e2f9572 --- /dev/null +++ b/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 `{ <> }`. 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::[] diff --git a/modules/ROOT/pages/errors/gql-errors/51N76.adoc b/modules/ROOT/pages/errors/gql-errors/51N76.adoc new file mode 100644 index 00000000..b6249cab --- /dev/null +++ b/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::[] diff --git a/modules/ROOT/pages/errors/gql-errors/index.adoc b/modules/ROOT/pages/errors/gql-errors/index.adoc index 4493c775..e1e914d4 100644 --- a/modules/ROOT/pages/errors/gql-errors/index.adoc +++ b/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 `{ <> }`. 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 `{ <> }` 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 diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 9b7f2912..6247bda9 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/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. ====