diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 10a9b8b..78eb847 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -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[] @@ -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[] 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 0000000..aa442cc --- /dev/null +++ b/modules/ROOT/pages/errors/gql-errors/42NAA.adoc @@ -0,0 +1,61 @@ += 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 + +[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::[] 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 0000000..3ac2df2 --- /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 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::[] diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 9b7f291..4e65b66 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -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. 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 @@ -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] ===== @@ -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>> + +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] =====