From 5f79778735f8816df646d0c5c6b62c2833d6d338 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 30 Oct 2024 19:11:30 +0000 Subject: [PATCH 01/29] Swamp the lagacy and the GQL code tab examples --- modules/ROOT/content-nav.adoc | 2 +- modules/ROOT/pages/draft.adoc | 23 + modules/ROOT/pages/errors/all-errors.adoc | 21 +- modules/ROOT/pages/errors/gql-errors.adoc | 2 +- modules/ROOT/pages/errors/index.adoc | 263 ++- modules/ROOT/pages/index.adoc | 63 +- .../notifications/all-notifications.adoc | 1477 ++++++++--------- modules/ROOT/pages/notifications/index.adoc | 59 +- 8 files changed, 993 insertions(+), 917 deletions(-) create mode 100644 modules/ROOT/pages/draft.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 0f0c9656..cfc4736f 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -1,7 +1,7 @@ * xref:index.adoc[] * xref:errors/index.adoc[] -** xref:errors/all-errors.adoc[] ** xref:errors/gql-errors.adoc[] +** xref:errors/all-errors.adoc[] * xref:notifications/index.adoc[] ** xref:notifications/all-notifications.adoc[] * xref:changelogs.adoc[] diff --git a/modules/ROOT/pages/draft.adoc b/modules/ROOT/pages/draft.adoc new file mode 100644 index 00000000..c6021a7f --- /dev/null +++ b/modules/ROOT/pages/draft.adoc @@ -0,0 +1,23 @@ +In GQL, when the execution of a GQL-request fails, the execution outcome (in this case failed outcome) has no results but only a primary GQL-status object describing the exception condition (i.e., the error) that caused the failure and possibly a list of other additional GQL-status objects describing other conditions related to the same GQL-request. + +A GQL-status object comprises: +A mandatory GQLSTATUS code, which is a 5 character string identifying a condition (the first 2 characters identify the GQLSTATUS class code and the 3 other characters identify the GQLSTATUS subclass code) +A mandatory status description, which is a user-facing message describing the GQLSTATUS +An optional record with diagnostic information (such as the code of the operation executed, the current working directory, etc.) +An optional nested GQL-status object for providing additional diagnostic information, such as a cause. +In GQL, it is up to implementations to make several conditions available when a GQL-request is executed. However, if multiple conditions are made available they should be returned in separate GQL-status objects. In this case, there should be a primary GQL-status object and a list of additional GQL-status objects. GQL prescribes the below precedence rules to determine the primary GQL-status object: +Every exception condition for transaction rollback has precedence over every other exception condition. +Every exception condition has precedence over every completion condition. +Note that GQL exception conditions are equivalent to Neo4j errors, and GQL completion conditions include Cypher notifications whose severity level is either warning or information (except those related to performance or variable shadowing, which are equivalent to GQL additional informational messages that can theoretically accompany both completion and exception condition). GQL completion conditions go beyond Cypher notifications. They include no data and successful completion. + + + + in Cypher, if the execution of a request fails, a single GQL-status object describing a specific error is returned, i.e., the primary GQL-status object, which is also GQL-compliant. This is different from the success case, where multiple Cypher notifications can be returned, hence multiple GQL-status objects describing completion conditions and informational conditions. + +Currently, a Neo4j error code can span several Neo4j exceptions and each exception can have several error messages. Each exception can be also linked to several Neo4j error codes. Some codes have no linked exceptions at all (See examples depicted in the table below). Hence, there is a many-to-many relationship between current error codes and exceptions. This is why many of the clients rely on the error message to identify a specific error. + +The ultimate goal is to have a 1-1 mapping between a GQLSTATUS code and a specific error message so as to let the client rely on one unique and standardized code. The next section describes how to assign a single and unique GQLSTATUS code for each error to achieve this goal. + +If a Neo4j error matches a standard-defined condition and subcondition, then the standard-defined GQLSTATUS code should be used for that error. For instance, (Neo.ClientError.Statement.ArithmeticError, ArithmeticException, “/by zero”) matches the “data exception” condition and “division by zero” subcondition in GQL (i.e., 22012 GQLSTATUS code). + +error: data exception - string data, right truncation \ No newline at end of file diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 28942cd0..61f372d2 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -1,8 +1,25 @@ -:description: The Neo4j error codes for Neo4j version {neo4j-version}. +:description: The legacy error codes for Neo4j 5. [[neo4j-errors]] -= List of all server error codes += List of legacy server error codes + +Error codes are Neo4j status codes returned by the server when the execution of a query fails. +They always have the severity level `ERROR`. +Errors are grouped based on the type of the error code: + +Client errors:: +These errors are caused by the client and are usually related to the request itself. +Client errors have the prefix `Neo.ClientError`. + +Transient errors:: +These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. +The error can be temporary and could therefore succeed if retrying the request. +Transient errors have the prefix Neo.`TransientError`. + +Database errors:: +These errors are caused by the database and are usually related to the database state. +Database errors have the prefix `Neo.DatabaseError`. This page contains lists of all Neo4j errors, grouped by type. diff --git a/modules/ROOT/pages/errors/gql-errors.adoc b/modules/ROOT/pages/errors/gql-errors.adoc index 27ddaa68..63c4716b 100644 --- a/modules/ROOT/pages/errors/gql-errors.adoc +++ b/modules/ROOT/pages/errors/gql-errors.adoc @@ -1,7 +1,7 @@ :description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur. [[neo4j-gqlstatus-errors]] -= List of all GQLSTATUS server error codes += List of GQLSTATUS server error codes //The following page provides an overview of all server errors in Neo4j, along with some scenarios and their possible solutions. The following page provides an overview of all GQLSTATUS server error codes in Neo4j. diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index 2d162cb9..597f5971 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -1,91 +1,180 @@ -:description: The Neo4j error codes for Neo4j version. +:description: This page describes the structure of the error objects, the error codes, and how to interpret them. [[neo4j-errors]] = Server errors -// [role=label--version-5.25] -// [[gqlstatus-error-object]] -// == GQL-status error object - -// [[gqlstatus-standard-defined-codes]] -// === Standard-defined GQLSTATUS codes - -// .Standard-defined GQLSTATUS error codes -// [options="header", cols="<1s,<4"] -// [%collapsible] -// |=== -// |GQLSTATUS code | StatusDescription -// | 08000 | error: connection exception -// | 08007 | error: connection exception - transaction resolution unknown -// | 22000 | error: data exception -// | 22001 | error: data exception - string data, right truncation -// | 22003 | error: data exception - numeric value out of range. The numeric value `$value` is outside the required range. -// | 22004 | error: data exception - null value not allowed -// | 22007 | error: data exception - invalid date, time, or datetime format -// | 22008 | error: data exception - datetime field overflow -// | 22011 | error: data exception - substring error -// | 22012 | error: data exception - division by zero -// | 22015 | error: data exception - interval field overflow -// | 22018 | error: data exception - invalid character value for cast. The character value `$value` is an invalid argument for the specified cast. -// | 2201E | error: data exception - invalid argument for natural logarithm. The value `$value` is an invalid argument for the specified natural logarithm. -// | 2201F | error: data exception - invalid argument for power function. The value `$value` is an invalid argument for the specified power function. -// | 22027 | error: data exception - trim error -// | 2202F | error: data exception - array data, right truncation -// | 22G02 | error: data exception - negative limit value -// | 22G03 | error: data exception - invalid value type -// | 22G04 | error: data exception - values not comparable -// | 22G05 | error: data exception - invalid date, time, or datetime function field name -// | 22G06 | error: data exception - invalid datetime function value -// | 22G07 | error: data exception - invalid duration function field name -// | 22G0B | error: data exception - list data, right truncation -// | 22G0C | error: data exception - list element error -// | 22G0F | error: data exception - invalid number of paths or groups -// | 22G0H | error: data exception - invalid duration format. The duration format `$format` is invalid. -// | 22G0M | error: data exception - multiple assignments to a graph element property -// | 22G0N | error: data exception - number of node labels below supported minimum -// | 22G0P | error: data exception - number of node labels exceeds supported maximum -// | 22G0Q | error: data exception - number of edge labels below supported minimum -// | 22G0R | error: data exception - number of edge labels exceeds supported maximum -// | 22G0S | error: data exception - number of node properties exceeds supported maximum -// | 22G0T | error: data exception - number of edge properties exceeds supported maximum -// | 22G0U | error: data exception - record fields do not match -// | 22G0V | error: data exception - reference value, invalid base type -// | 22G0W | error: data exception - reference value, invalid constrained type -// | 22G0X | error: data exception - record data, field unassignable -// | 22G0Y | error: data exception - record data, field missing -// | 22G0Z | error: data exception - malformed path -// | 22G10 | error: data exception - path data, right truncation -// | 22G11 | error: data exception - reference value, referent deleted -// | 22G13 | error: data exception - invalid group variable value -// | 22G14 | error: data exception - incompatible temporal instant unit groups -// | 25000 | error: invalid transaction state -// | 25G01 | error: invalid transaction state - active GQL-transaction -// | 25G02 | error: invalid transaction state - catalog and data statement mixing not supported -// | 25G03 | error: invalid transaction state - read-only GQL-transaction -// | 25G04 | error: invalid transaction state - accessing multiple graphs not supported -// | 2D000 | error: invalid transaction termination -// | 40000 | error: transaction rollback -// | 40003 | error: transaction rollback - statement completion unknown -// | 42000 | error: syntax error or access rule violation -// | 42001 | error: syntax error or access rule violation - invalid syntax -// | 42002 | error: syntax error or access rule violation - invalid reference -// | 42004 | error: syntax error or access rule violation - use of visually confusable identifiers -// | 42006 | error: syntax error or access rule violation - number of edge labels below supported minimum -// | 42007 | error: syntax error or access rule violation - number of edge labels exceeds supported maximum -// | 42008 | error: syntax error or access rule violation - number of edge properties exceeds supported maximum -// | 42009 | error: syntax error or access rule violation - number of node labels below supported minimum -// | 42010 | error: syntax error or access rule violation - number of node labels exceeds supported maximum -// | 42011 | error: syntax error or access rule violation - number of node properties exceeds supported maximum -// | 42012 | error: syntax error or access rule violation - number of node type key labels below supported minimum -// | 42013 | error: syntax error or access rule violation - number of node type key labels exceeds supported maximum -// | 42014 | error: syntax error or access rule violation - number of edge type key labels below supported minimum -// | 42015 | error: syntax error or access rule violation - number of edge type key labels exceeds supported maximum -// | G1000 | error: dependent object error -// | G1001 | error: dependent object error - edges still exist -// | G1002 | error: dependent object error - endpoint node is deleted -// | G1003 | error: dependent object error - endpoint node not in current working graph -// | G2000 | error: graph type violation -// |=== - -// [[gqlstatus-neo4j-defined-codes]] -// === Neo4j-defined GQLSTATUS error codes +A server error is returned by the Neo4j DBMS to indicate that the outcome of a Cypher query or command execution is not successful. +The driver receives these errors and sends them to the client, which displays them to the user. +Starting from version 5.25, Neo4j has a new GqlStatusObject API in addition to the existing HasStatus API. +The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. + +This page describes both the Neo4j error and the GQL-status object frameworks, how they are structured, the objects they provide for errors, and how to interpret them. +//It also explains the server error grouping and filtering, the error internals, and the server-driver compatibility for both the HasStatus and GqlStatusObject APIs. + + +[role=label--version-5.23] +[[gqlstatus-error-object]] +== GQL-status error object + +In the GQL-status object framework, errors are an implementation-defined subset of the GQL-status objects that cover exceptions. + +In GQL, the execution of a query from user to server always has an outcome, called the _execution outcome_. +The execution outcome is a list of GQL-status objects, ordered by the following precedence, where the first object in the list is the primary GQL-status object: + +. Every exception condition for transaction rollback has precedence over every other exception condition. +. Every exception condition has precedence over every completion condition. + +The GQL-status object also includes the Neo4j-specific information, such as the severity level and the classification of the error. + +Each GQL-status object consists of the following fields: + +.GQLSTATUS error object +[cols="<1s,<4"] +|=== +|GQLSTATUS code +a| A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code. +|StatusDescription +a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and a description. +The condition and subcondition are textual representations of the class and subclass codes, respectively. +| DiagnosticRecord +a| Extra information about the status, given as key-value pairs, both on the server and driver side. +To retrieve the full diagnostic record, you can use the `diagnosticRecord()` method on both the server and driver sides. +Additional helper methods are exposed for some useful fields. +[cols="<1s,<4"] +!=== +! Field ! Description +! `OPERATION` ! The operation that the error is related to. Always defaults to empty. +! `OPERATION_CODE` ! The operation code that the error is related to. Always defaults to `0`. +! `CURRENT_SCHEMA` ! The current schema that the error is related to. Always defaults to `/`. +! `_severity` a! The Neo4j severity level of the error, which is always `ERROR`. +!`_classification` ! The Neo4j category of the error, which can be `CLIENT_ERROR`, `TRANSIENT_ERROR`, or `DATABASE_ERROR`. +! `_position` ! The position, given by row and column, where the error is relevant in the query text. +//! `_status_parameters`! A map that contains all variable parts of the status description. +!=== +|=== + +A GQL-status error object can also contain an optional nested GQL-status object for providing additional diagnostic information, such as a cause, which is a GQL-status object wrapped in another GQL-status object. + +[[gqlstatus-neo4j-defined-codes]] +== Classes of GQLSTATUS error codes + +The Neo4j-defined GQLSTATUS codes are divided into classes and subclasses, where the class code is a 2-character string (one of `00`, `01`, or `03`) and the subclass code is a 3-character string. +The class code indicates the general condition of the status (such as successful completion, warning, or information), and the subclass code provides more detailed information about the condition, such as classification and messages. + +The following table lists the Neo4j-defined groups of GQLSTATUS codes and their meanings: + +.GQLSTATUS groups of codes as defined by Neo4j +[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] +|=== +|GQLSTATUS code +|*Description* + +| 01N0[y] +| Deprecation warnings + +| 01N3[y] +| Hint warnings + +| 01N4[y] +| Unsupported warnings + +| 01N5[y] +| Unrecognized warnings + +| 01N6[y] +| Generic warnings + +| 01N7[y] +| Security warnings + +| 03N9[y] +| Performance information + +| 03N6[y] +| Generic information + +| 00N5[y] +| Unrecognized information under successful completion + +| 00N6[y] +| Generic information under successful completion + +| 00N7[y] +| Security information under successful completion + +| 00N8[y] +| Topology information under successful completion + +|=== + +[[neo4j-error-object]] +== Neo4j error object + +The Neo4j error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. +Depending on the application, some of the fields from the error object might not be visible. + +The error object consists of the following fields: + +.Neo4j error object +[cols="<1s,<4"] +|=== +|Neo4j code +a|The Neo4j status code in the form of `Neo.[Type].[SubType].[Name]`. +|Description +a|The description of the specific error. +|Message +a|The error message. +|Severity level +a|`ERROR` +|Category +a|The category of the error. +Available categories are `CLIENT_ERROR`, `TRANSIENT_ERROR`, and `DATABASE_ERROR`. +|Position +a|The position, given by row and column, where the error is relevant in the query text. +|=== + +[[error-grouping-and-filtering]] +== Server error classification + +The fact that a Neo4j status code is returned by the server does not always mean there is a fatal error. +Neo4j status codes can also indicate transient problems that may go away if you retry the request. +The status code classification determines the effect on the transaction. + +.Neo4j status code types +[options="header", cols="<1m,<2,<1"] +|=== + +| Type +| Description +| Effect on the transaction + +| xref:errors/all-errors.adoc#_client_errors[ClientError] +| The client sent a bad request - changing the request might yield a successful outcome. +| Rollback + +| xref:errors/all-errors#_transient_errors[TransientError] +| The database cannot service the request right now, retrying later might yield a successful outcome. +| Rollback + +| xref:errors/all-errors#_database_error[DatabaseError] +| The database failed to service the request. +| Rollback + +|=== + +[[error-internals]] +== Error internals + +The server and driver communicate with each other through the Bolt protocol. +During the handshake process, they agree on using the newest possible Bolt protocol version that both the server and the driver support. +For more information on the Bolt versions supported by different server versions, see the link:https://neo4j.com/docs/bolt/current/bolt-compatibility[Bolt Protocol documentation]. + +Neo4j supports server errors in the form of Java exceptions. +Most of these implement the `HasStatus` interface, which means they have a Neo4j status code in addition to the exception message. + +On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the Neo4j status code. +These exceptions are then sent to the driver as failure Bolt message metadata. + + +[[server-driver-compatibility]] +== Server-driver version compatibility \ No newline at end of file diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index f24b4167..b0081f36 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -9,64 +9,17 @@ endif::[] :description: The Neo4j status codes for Neo4j version {neo4j-version}. :neo4j-buildnumber: {neo4j-version} +The Neo4j 5 Status Codes manual includes all status codes that a Neo4j server may return to indicate the outcome of a Cypher request. -This document details all status codes that a Neo4j DBMS may return to indicate the outcome of a request. +Starting from 5.23 for notifications and 5.25 for errors, the Neo4j DBMS supports the GQL standard. + +GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases. +Cypher®, Neo4j’s query language, supports most mandatory and a substantial portion of the optional GQL features (as defined by the ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard). +For more information, see link:https:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance]. -//== GQL status codes +As part of this GQL compliance, Cypher now also include status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. +For more information on GQL status code framewoks for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. - -== Neo4j status codes - -=== Format - -Each Neo4j status code follows the same format: - -[source, status code format, role="noheader"] ------ -Neo.[Type].[SubType].[Name] ------ - - -=== Types of Neo4j status codes - -The fact that a Neo4j status code is returned by the server does not always mean there is a fatal error. -Neo4j status codes can also indicate transient problems that may go away if you retry the request. -The type of the status code determines the effect on the transaction. - -.Neo4j status code types -[options="header", cols="<1m,<2,<1"] -|=== - -| Type -| Description -| Effect on the transaction - -| xref:errors/all-errors.adoc#_client_errors[ClientError] -| The client sent a bad request - changing the request might yield a successful outcome. -| Rollback - -| xref:errors/all-errors#_transient_errors[TransientError] -| The database cannot service the request right now, retrying later might yield a successful outcome. -| Rollback - -| xref:errors/all-errors#_database_error[DatabaseError] -| The database failed to service the request. -| Rollback - -| xref:notifications/index.adoc[ClientNotifications] -| The query execution was successful, but there are notifications about the request sent by the client. -| None - -|=== - -[NOTE] -==== -From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API. - -The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. -It includes GQLSTATUS code, StatusDescription, and DiagnosticRecord. -For more information, see xref:notifications/index.adoc#gqlstatus-notification-object[GQL-status notification object]. -==== +This manual details all status codes that a Neo4j DBMS may return, including both GQL-compliant and legacy status codes. ifndef::backend-pdf[] License: link:{common-license-page-uri}[Creative Commons 4.0] diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index f7c0a2f2..9d927abb 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -3,7 +3,7 @@ [[listOfNnotifications]] = List of all server notification codes -The following page provides an overview of all notifications in Neo4j, along with some scenarios and their possible solutions. +The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and the legacy Neo4j codes, along with some scenarios and their possible solutions. * <<_performance_notifications, `PERFORMANCE` notifications>> * <<_hint_notifications, `HINT` notifications>> @@ -29,7 +29,7 @@ This notification is returned when there is a Cartesian product in the plan. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.CartesianProduct |Title a|This query builds a cartesian product between disconnected patterns. @@ -53,7 +53,7 @@ m|INFORMATION .A query that contains many disconnected patterns [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -63,12 +63,13 @@ Query:: MATCH (c:Child), (p:Parent) RETURN c, p ---- -Description of the returned code:: -If a part of a query contains multiple disconnected patterns, -this will build a cartesian product between all those parts. -This may produce a large amount of data and slow down query processing. -While occasionally intended, it may often be possible to reformulate the query that avoids the use of this cross product, -perhaps by adding a relationship between the different parts or by using `OPTIONAL MATCH` (identifier is: (`p`)) +Returned GQLSTATUS code:: +03N90 + +Returned status description:: +info: cartesian product. +The disconnected patterns `(c:Child), (p:Parent)` build a cartesian product. +A cartesian product may produce a large amount of data and slow down query processing. Suggestions for improvement:: In case a Cartesian product is needed, nothing can be done to improve this query. @@ -81,7 +82,7 @@ MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -91,13 +92,12 @@ Query:: MATCH (c:Child), (p:Parent) RETURN c, p ---- -Returned GQLSTATUS code:: -03N90 - -Returned status description:: -info: cartesian product. -The disconnected patterns `(c:Child), (p:Parent)` build a cartesian product. -A cartesian product may produce a large amount of data and slow down query processing. +Description of the returned code:: +If a part of a query contains multiple disconnected patterns, +this will build a cartesian product between all those parts. +This may produce a large amount of data and slow down query processing. +While occasionally intended, it may often be possible to reformulate the query that avoids the use of this cross product, +perhaps by adding a relationship between the different parts or by using `OPTIONAL MATCH` (identifier is: (`p`)) Suggestions for improvement:: In case a Cartesian product is needed, nothing can be done to improve this query. @@ -120,7 +120,7 @@ This notification is returned when there is no upper bound specified on the vari .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.UnboundedVariableLengthPattern |Title a|The provided pattern is unbounded, consider adding an upper limit to the number of node hops. @@ -144,7 +144,7 @@ m|INFORMATION .Shortest path with an unbounded pattern [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -156,9 +156,14 @@ WHERE n <> m RETURN p ---- -Description of the returned code:: -Using shortest path with an unbounded pattern will likely result in long execution times. -It is recommended to use an upper limit to the number of node hops in your pattern. +Returned GQLSTATUS code:: +03N91 + +Returned status description:: +info: unbounded variable length pattern. +The provided pattern `(n)-[\*]->(m)` is unbounded. +Shortest path with an unbounded pattern may result in long execution times. +Use an upper limit (e.g. `[*..5]`) on the number of node hops in your pattern. Suggestions for improvement:: If you have a big graph, this query might be very slow. @@ -171,26 +176,19 @@ WHERE n <> m RETURN p ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + [source, cypher, role="noplay"] ---- -MATCH p=shortestPath((n)-[*]->(m)) -WHERE n <> m -RETURN p +MATCH p=shortestPath((n)-[*]->(m)) RETURN p ---- -Returned GQLSTATUS code:: -03N91 - -Returned status description:: -info: unbounded variable length pattern. -The provided pattern `(n)-[\*]->(m)` is unbounded. -Shortest path with an unbounded pattern may result in long execution times. -Use an upper limit (e.g. `[*..5]`) on the number of node hops in your pattern. +Description of the returned code:: +Using shortest path with an unbounded pattern will likely result in long execution times. +It is recommended to use an upper limit to the number of node hops in your pattern. Suggestions for improvement:: If you have a big graph, this query might be very slow. @@ -198,9 +196,7 @@ Consider adding an upper limit. + [source, cypher, role="noplay"] ---- -MATCH p=shortestPath((n)-[*..8]->(m)) -WHERE n <> m -RETURN p +MATCH p=shortestPath((n)-[*..8]->(m)) RETURN p ---- ====== ===== @@ -214,7 +210,7 @@ For more information, see link:https://neo4j.com/docs/cypher-manual/current/exec .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.ExhaustiveShortestPath |Title a|Exhaustive shortest path has been planned for your query that means that shortest path graph algorithm might not be used to find the shortest path. @@ -239,7 +235,7 @@ m|INFORMATION .A query that runs with an exhaustive shortest path [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -250,9 +246,13 @@ WHERE ANY(n in nodes(p) WHERE n:Label) RETURN p ---- -Description of the returned code:: -Using shortest path with an exhaustive search fallback might cause query slow down since shortest path graph algorithms might not work for this use case. -It is recommended to introduce a `WITH` to separate the `MATCH` containing the shortest path from the existential predicates on that path. +Returned GQLSTATUS code:: +03N92 + +Returned status description:: +info: exhaustive shortest path. +The query runs with exhaustive shortest path due to the existential predicate(s) `ANY(n in nodes(p) WHERE n:Label)`. +It may be possible to use `WITH` to separate the `MATCH` from the existential predicate(s). Suggestions for improvement:: Separate the predicate by introducing a `WITH` after the `MATCH` clause. @@ -265,7 +265,7 @@ WHERE ANY(n in nodes(p) WHERE n:Label) RETURN p ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -276,13 +276,9 @@ WHERE ANY(n in nodes(p) WHERE n:Label) RETURN p ---- -Returned GQLSTATUS code:: -03N92 - -Returned status description:: -info: exhaustive shortest path. -The query runs with exhaustive shortest path due to the existential predicate(s) `ANY(n in nodes(p) WHERE n:Label)`. -It may be possible to use `WITH` to separate the `MATCH` from the existential predicate(s). +Description of the returned code:: +Using shortest path with an exhaustive search fallback might cause query slow down since shortest path graph algorithms might not work for this use case. +It is recommended to introduce a `WITH` to separate the `MATCH` containing the shortest path from the existential predicates on that path. Suggestions for improvement:: Separate the predicate by introducing a `WITH` after the `MATCH` clause. @@ -307,7 +303,7 @@ Adding an index could improve the query speed. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.NoApplicableIndex |Title a|Adding a schema index may speed up this query. @@ -331,7 +327,7 @@ m|INFORMATION .`LOAD CSV` with `MATCH` or `MERGE` [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -341,9 +337,13 @@ Query:: LOAD CSV FROM 'file:///ignore/ignore.csv' AS line WITH * MATCH (n:Person{name:line[0]}) RETURN line, n ---- -Description of the returned code:: -Using `LOAD CSV` followed by a `MATCH` or `MERGE` that matches a non-indexed label will most likely not perform well on large data sets. -Please consider using a schema index. +Returned GQLSTATUS code:: +03N93 + +Returned status description:: +info: no applicable index. +`LOAD CSV` in combination with `MATCH` or `MERGE` on a label that does not have an index may result in long execution times. +Consider adding an index for label `Person`. Suggestions for improvement:: Create an index on the label and property you match. @@ -352,9 +352,8 @@ Create an index on the label and property you match. ---- CREATE INDEX FOR (n:Person) ON (n.name) ---- - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -364,13 +363,9 @@ Query:: LOAD CSV FROM 'file:///ignore/ignore.csv' AS line WITH * MATCH (n:Person{name:line[0]}) RETURN line, n ---- -Returned GQLSTATUS code:: -03N93 - -Returned status description:: -info: no applicable index. -`LOAD CSV` in combination with `MATCH` or `MERGE` on a label that does not have an index may result in long execution times. -Consider adding an index for label `Person`. +Description of the returned code:: +Using `LOAD CSV` followed by a `MATCH` or `MERGE` that matches a non-indexed label will most likely not perform well on large data sets. +Please consider using a schema index. Suggestions for improvement:: Create an index on the label and property you match. @@ -379,6 +374,7 @@ Create an index on the label and property you match. ---- CREATE INDEX FOR (n:Person) ON (n.name) ---- + ====== ===== @@ -390,7 +386,7 @@ This notification is returned when the execution plan for a query contains the ` .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.EagerOperator |Title a|The execution plan for this query contains the Eager operator, which forces all dependent data to be materialized in main memory before proceeding @@ -414,11 +410,9 @@ m|INFORMATION .`LOAD CSV` with an Eager operator [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== -`LOAD CSV` together with an Eager operator can take up a lot of memory. - Query:: + [source, cypher, role="noplay"] @@ -426,9 +420,13 @@ Query:: LOAD CSV FROM 'file:///ignore/ignore.csv' AS line MATCH (n:Person{name:line[0]}) DELETE n RETURN line ---- -Description of the returned code:: -Using `LOAD CSV` with a large data set in a query where the execution plan contains the Eager operator could potentially consume a lot of memory and is likely to not perform well. -See the Neo4j Manual entry on the Eager operator for more information and hints on how problems could be avoided. +Returned GQLSTATUS code:: +03N94 + +Returned status description:: +info: eager operator. +The query execution plan contains the `Eager` operator. +`LOAD CSV` in combination with `Eager` can consume a lot of memory. Suggestions for improvement:: See the link:https://neo4j.com/docs/cypher-manual/current/planning-and-tuning/operators/operators-detail/#query-plan-eager[Cypher Manual -> Eager operator] for more information and hints on how to avoid problems. @@ -443,11 +441,12 @@ CALL { } RETURN line ---- - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== +`LOAD CSV` together with an Eager operator can take up a lot of memory. + Query:: + [source, cypher, role="noplay"] @@ -455,13 +454,9 @@ Query:: LOAD CSV FROM 'file:///ignore/ignore.csv' AS line MATCH (n:Person{name:line[0]}) DELETE n RETURN line ---- -Returned GQLSTATUS code:: -03N94 - -Returned status description:: -info: eager operator. -The query execution plan contains the `Eager` operator. -`LOAD CSV` in combination with `Eager` can consume a lot of memory. +Description of the returned code:: +Using `LOAD CSV` with a large data set in a query where the execution plan contains the Eager operator could potentially consume a lot of memory and is likely to not perform well. +See the Neo4j Manual entry on the Eager operator for more information and hints on how problems could be avoided. Suggestions for improvement:: See the link:https://neo4j.com/docs/cypher-manual/current/planning-and-tuning/operators/operators-detail/#query-plan-eager[Cypher Manual -> Eager operator] for more information and hints on how to avoid problems. @@ -476,6 +471,7 @@ CALL { } RETURN line ---- + ====== ===== @@ -486,7 +482,7 @@ RETURN line .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.DynamicProperty |Title a|Queries using dynamic properties will use neither index seeks nor index scans for those properties @@ -510,7 +506,7 @@ m|INFORMATION .A dynamic node property key makes it impossible to use indexes [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -520,8 +516,14 @@ Query:: MATCH (n:Person) WHERE n[$prop] IS NOT NULL RETURN n; ---- -Description of the returned code:: -Using a dynamic property makes it impossible to use an index lookup for this query (indexed label is: `Person`) +Returned GQLSTATUS code:: +03N95 + +Returned status description:: +info: dynamic property. +An index exists on label/type(s) `Person`. +It is not possible to use indexes for dynamic properties. +Consider using static properties. Suggestions for improvement:: If there is an index for `(n:Person) ON (n.name)`, it will not be used for the above query because the query is using a dynamic property. @@ -534,7 +536,7 @@ MATCH (n:Person) WHERE n.name IS NOT NULL RETURN n; ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -544,14 +546,8 @@ Query:: MATCH (n:Person) WHERE n[$prop] IS NOT NULL RETURN n; ---- -Returned GQLSTATUS code:: -03N95 - -Returned status description:: -info: dynamic property. -An index exists on label/type(s) `Person`. -It is not possible to use indexes for dynamic properties. -Consider using static properties. +Description of the returned code:: +Using a dynamic property makes it impossible to use an index lookup for this query (indexed label is: `Person`) Suggestions for improvement:: If there is an index for `(n:Person) ON (n.name)`, it will not be used for the above query because the query is using a dynamic property. @@ -569,7 +565,7 @@ MATCH (n:Person) WHERE n.name IS NOT NULL RETURN n; .A dynamic relationship property key makes it impossible to use indexes [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -579,8 +575,14 @@ Query:: MATCH ()-[r: KNOWS]->() WHERE r[$prop] IS NOT NULL RETURN r ---- -Description of the returned code:: -Using a dynamic property makes it impossible to use an index lookup for this query (indexed type is: `KNOWS`) +Returned GQLSTATUS code:: +03N95 + +Returned status description:: +info: dynamic property. +An index exists on label/type(s) `KNOWS`. +It is not possible to use indexes for dynamic properties. +Consider using static properties. Suggestions for improvement:: Similar to dynamic node properties, use a constant value if possible, especially when there is an index on the relationship property. @@ -592,7 +594,7 @@ MATCH ()-[r: KNOWS]->() WHERE r.since IS NOT NULL RETURN r ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -602,18 +604,12 @@ Query:: MATCH ()-[r: KNOWS]->() WHERE r[$prop] IS NOT NULL RETURN r ---- -Returned GQLSTATUS code:: -03N95 - -Returned status description:: -info: dynamic property. -An index exists on label/type(s) `KNOWS`. -It is not possible to use indexes for dynamic properties. -Consider using static properties. +Description of the returned code:: +Using a dynamic property makes it impossible to use an index lookup for this query (indexed type is: `KNOWS`) Suggestions for improvement:: Similar to dynamic node properties, use a constant value if possible, especially when there is an index on the relationship property. -For example, if `{ $prop }` is equal to `since`, you can rewrite the query to: +For example, if `$prop` is equal to `since`, you can rewrite the query to: + [source, cypher] ---- @@ -632,7 +628,7 @@ For more information about the specific query, see the stack trace in the _debug .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.CodeGenerationFailed |Title a|The database was unable to generate code for the query. A stacktrace can be found in the _debug.log_. @@ -667,7 +663,7 @@ In this case, the query will return an error. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.JoinHintUnfulfillableWarning |Title a|The database was unable to plan a hinted join. @@ -690,7 +686,7 @@ m|WARNING .Inability to fulfill the hint despite the given `JOIN` hint [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -705,17 +701,20 @@ OPTIONAL MATCH (a)--(c) RETURN * ---- -Description of the returned code:: -The hinted join was not planned. -This could happen because no generated plan contained the join key, -please try using a different join key or restructure your query. (hinted join key identifier is: `a`) +Returned GQLSTATUS code:: +01N30 + +Returned status description:: +warn: joint hint unfulfillable. +Unable to create a plan with `JOIN ON a`. +Try to change the join key(s) or restructure your query. Suggestions for improvement:: The `JOIN` hint cannot be applied because its specified variable is before the `OPTIONAL MATCH` and, therefore, is already bound. The only option for this query is to either remove the hint or modify the query to allow it to be used. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -730,13 +729,10 @@ OPTIONAL MATCH (a)--(c) RETURN * ---- -Returned GQLSTATUS code:: -01N30 - -Returned status description:: -warn: joint hint unfulfillable. -Unable to create a plan with `JOIN ON a`. -Try to change the join key(s) or restructure your query. +Description of the returned code:: +The hinted join was not planned. +This could happen because no generated plan contained the join key, +please try using a different join key or restructure your query. (hinted join key identifier is: `a`) Suggestions for improvement:: The `JOIN` hint cannot be applied because its specified variable is before the `OPTIONAL MATCH` and, therefore, is already bound. @@ -752,7 +748,7 @@ The only option for this query is to either remove the hint or modify the query .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Schema.HintedIndexNotFound |Title a|The request (directly or indirectly) referred to an index that does not exist. @@ -774,7 +770,7 @@ m|WARNING .Inability to use the label index despite the given index hint [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -787,15 +783,18 @@ WHERE a.id = 1 RETURN a ---- -Description of the returned code:: -The hinted index does not exist, please check the schema (index is: INDEX FOR (`a`:`Label`) ON (`a`.`id`)) +Returned GQLSTATUS code:: +01N31 + +Returned status description:: +warn: hinted index not found. +Unable to create a plan with `INDEX :Label(id)` because the index does not exist. Suggestions for improvement:: The hinted index does not exist, make sure the label and property are spelled correctly. If the spelling is correct, either create the index or remove the hint from the query. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -808,23 +807,20 @@ WHERE a.id = 1 RETURN a ---- -Returned GQLSTATUS code:: -01N31 - -Returned status description:: -warn: hinted index not found. -Unable to create a plan with `INDEX :Label(id)` because the index does not exist. +Description of the returned code:: +The hinted index does not exist, please check the schema (index is: INDEX FOR (`a`:`Label`) ON (`a`.`id`)) Suggestions for improvement:: The hinted index does not exist, make sure the label and property are spelled correctly. If the spelling is correct, either create the index or remove the hint from the query. + ====== ===== .Inability to use the relationship index despite the given index hint [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -837,15 +833,18 @@ WHERE r.id = 1 RETURN r ---- -Description of the returned code:: -The hinted index does not exist, please check the schema (index is: INDEX FOR ()-[`r`:`Rel`]-() ON (`r`.`id`)) +Returned GQLSTATUS code:: +01N31 + +Returned status description:: +warn: hinted index not found. +Unable to create a plan with `INDEX :Rel(id)` because the index does not exist. Suggestions for improvement:: The hinted index does not exist, make sure the relationship type and property are spelled correctly. If the spelling is correct, either create the index or remove the hint from the query. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -858,16 +857,13 @@ WHERE r.id = 1 RETURN r ---- -Returned GQLSTATUS code:: -01N31 - -Returned status description:: -warn: hinted index not found. -Unable to create a plan with `INDEX :Rel(id)` because the index does not exist. +Description of the returned code:: +The hinted index does not exist, please check the schema (index is: INDEX FOR ()-[`r`:`Rel`]-() ON (`r`.`id`)) Suggestions for improvement:: The hinted index does not exist, make sure the relationship type and property are spelled correctly. If the spelling is correct, either create the index or remove the hint from the query. + ====== ===== @@ -882,7 +878,7 @@ Unrecognized notifications are returned when the query or command mentions entit .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Database.HomeDatabaseNotFound |Title a|The request referred to a home database that does not exist. @@ -906,7 +902,7 @@ m|INFORMATION .Setting the `home` database to a database that does not exist [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -916,15 +912,18 @@ Query:: CREATE USER john SET PASSWORD "secret" SET HOME DATABASE nej4 ---- -Description of the returned code:: -The home database provided does not currently exist in the DBMS. -This command will not take effect until this database is created. (HOME DATABASE: `nej4`) +Returned GQLSTATUS code:: +00N50 + +Returned status description:: +note: successful completion - home database not found. +The database `ne4j` does not exist. +Verify that the spelling is correct or create the database for the command to take effect. Suggestions for improvement:: Verify that the home database name is not misspelled. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -934,16 +933,13 @@ Query:: CREATE USER john SET PASSWORD "secret" SET HOME DATABASE nej4 ---- -Returned GQLSTATUS code:: -00N50 - -Returned status description:: -note: successful completion - home database not found. -The database `ne4j` does not exist. -Verify that the spelling is correct or create the database for the command to take effect. +Description of the returned code:: +The home database provided does not currently exist in the DBMS. +This command will not take effect until this database is created. (HOME DATABASE: `nej4`) Suggestions for improvement:: Verify that the home database name is not misspelled. + ====== ===== @@ -953,7 +949,7 @@ Verify that the home database name is not misspelled. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.UnknownLabelWarning |Title a|The provided label is not in the database. @@ -976,7 +972,7 @@ m|WARNING .Matching on a node with a label that does not exist in the database [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: @@ -986,15 +982,19 @@ Query:: MATCH (n:Perso) RETURN n ---- -Description of the returned code:: -One of the labels in your query is not available in the database, make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing label name is: `Perso`) +Returned GQLSTATUS code:: +01N50 + +Returned status description:: +warn: unknown label. +The label `Perso` does not exist. +Verify that the spelling is correct. Suggestions for improvement:: Verify that the label is not misspelled. -If you plan to create nodes with that label in the future, then no change is needed. - +If you plan to create nodes with that label in the future, no change is needed. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: @@ -1004,17 +1004,13 @@ Query:: MATCH (n:Perso) RETURN n ---- -Returned GQLSTATUS code:: -01N50 - -Returned status description:: -warn: unknown label. -The label `Perso` does not exist. -Verify that the spelling is correct. +Description of the returned code:: +One of the labels in your query is not available in the database, make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing label name is: `Perso`) Suggestions for improvement:: Verify that the label is not misspelled. -If you plan to create nodes with that label in the future, no change is needed. +If you plan to create nodes with that label in the future, then no change is needed. + ====== ===== @@ -1024,7 +1020,7 @@ If you plan to create nodes with that label in the future, no change is needed. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.UnknownRelationshipTypeWarning |Title a|The provided relationship type is not in the database. @@ -1048,7 +1044,7 @@ m|WARNING .Matching a relationship with a type that does not exist [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -1057,16 +1053,19 @@ Query:: MATCH (n)-[:NonExistingType]->() RETURN n ---- -Description of the returned code:: -One of the relationship types in your query is not available in the database, -make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing relationship type is: `NonExistingType`) +Returned GQLSTATUS code:: +01N51 + +Returned status description:: +warn: unknown relationship type. +The relationship type `NonExistingType` does not exist. +Verify that the spelling is correct. Suggestions for improvement:: Verify that the relationship type is not misspelled. If you plan to create relationships of this type in the future, no change is needed. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -1075,17 +1074,14 @@ Query:: MATCH (n)-[:NonExistingType]->() RETURN n ---- -Returned GQLSTATUS code:: -01N51 - -Returned status description:: -warn: unknown relationship type. -The relationship type `NonExistingType` does not exist. -Verify that the spelling is correct. +Description of the returned code:: +One of the relationship types in your query is not available in the database, +make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing relationship type is: `NonExistingType`) Suggestions for improvement:: Verify that the relationship type is not misspelled. If you plan to create relationships of this type in the future, no change is needed. + ====== ===== @@ -1095,7 +1091,7 @@ If you plan to create relationships of this type in the future, no change is nee .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.UnknownPropertyKeyWarning |Title a|The provided property key is not in the database @@ -1119,7 +1115,7 @@ m|WARNING .Matching a property key that does not exist [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -1129,16 +1125,19 @@ MATCH (n:Person {nme:”Tom”}) RETURN n ---- -Description of the returned code:: -One of the property names in your query is not available in the database, -make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing property name is: `nme`) +Returned GQLSTATUS code:: +01N52 + +Returned status description:: +warn: unknown property key. +The property `nme` does not exist. +Verify that the spelling is correct. Suggestions for improvement:: Verify that the property key is not misspelled. If you plan to create that property key in the future, no change is needed. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -1148,17 +1147,14 @@ MATCH (n:Person {nme:”Tom”}) RETURN n ---- -Returned GQLSTATUS code:: -01N52 - -Returned status description:: -warn: unknown property key. -The property `nme` does not exist. -Verify that the spelling is correct. +Description of the returned code:: +One of the property names in your query is not available in the database, +make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing property name is: `nme`) Suggestions for improvement:: Verify that the property key is not misspelled. If you plan to create that property key in the future, no change is needed. + ====== ===== @@ -1168,7 +1164,7 @@ If you plan to create that property key in the future, no change is needed. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.AggregationSkippedNull |Title a|The query contains an aggregation function that skips null values. @@ -1189,17 +1185,6 @@ m|WARNING .Aggregation skipping a NULL value [.tabbed-example] ===== -[.include-with-neo4j-code] -====== -Query:: - -[source,cypher] ----- -UNWIND [1, NULL, 2] AS i RETURN count(i) AS sum ----- -Description of the returned code:: -The query contains an aggregation function that skips null values. -====== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1215,6 +1200,17 @@ Returned GQLSTATUS code:: Returned status description:: warn: null value eliminated in set function. ====== +[.include-with-neo4j-legacy-code] +====== +Query:: + +[source,cypher] +---- +UNWIND [1, NULL, 2] AS i RETURN count(i) AS sum +---- +Description of the returned code:: +The query contains an aggregation function that skips null values. +====== ===== [#_unsupported_notifications] @@ -1228,7 +1224,7 @@ Unsupported notifications are returned when the query or command is trying to us .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.RuntimeUnsupportedWarning |Title a|This query is not supported by the chosen runtime. @@ -1252,19 +1248,22 @@ m|WARNING .A runtime is not supported by a Cypher command [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== - Query:: + [source,cypher] ---- -CYPHER runtime=pipelined SHOW INDEXES YIELD * +EXPLAIN CYPHER runtime=pipelined SHOW INDEXES YIELD * ---- -Description of the returned code:: -Selected runtime is unsupported for this query, please use a different runtime instead or fallback to default. -(Pipelined does not yet support the plans including `ShowIndexes`, use another runtime.) +Returned GQLSTATUS code:: +01N40 + +Returned status description:: +warn: unsupported runtime. +The query cannot be executed with `runtime=pipelined`, `runtime=slotted` is used. +Cause: Pipelined does not yet support the plans including `ShowIndexes`, use another runtime. Suggestions for improvement:: Use a different runtime or remove the runtime option to run the query with the default runtime: @@ -1273,24 +1272,20 @@ Use a different runtime or remove the runtime option to run the query with the d ---- SHOW INDEXES YIELD * ---- - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== + Query:: + [source,cypher] ---- -EXPLAIN CYPHER runtime=pipelined SHOW INDEXES YIELD * +CYPHER runtime=pipelined SHOW INDEXES YIELD * ---- -Returned GQLSTATUS code:: -01N40 - -Returned status description:: -warn: unsupported runtime. -The query cannot be executed with `runtime=pipelined`, `runtime=slotted` is used. -Cause: Pipelined does not yet support the plans including `ShowIndexes`, use another runtime. +Description of the returned code:: +Selected runtime is unsupported for this query, please use a different runtime instead or fallback to default. +(Pipelined does not yet support the plans including `ShowIndexes`, use another runtime.) Suggestions for improvement:: Use a different runtime or remove the runtime option to run the query with the default runtime: @@ -1299,6 +1294,7 @@ Use a different runtime or remove the runtime option to run the query with the d ---- SHOW INDEXES YIELD * ---- + ====== ===== @@ -1314,7 +1310,7 @@ The usage of this notification has been removed since Neo4j 5.14. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.RuntimeExperimental |Title a|This feature is experimental and should not be used in production systems. @@ -1359,7 +1355,7 @@ It is important to change to the new functionality, otherwise, the query might b .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -1392,7 +1388,7 @@ m|WARNING .Create a database with an unescaped name containing a dot [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -1401,9 +1397,12 @@ Query:: CREATE DATABASE foo.bar ---- -Description of the returned code:: -Databases and aliases with unescaped `.` are deprecated unless to indicate that they belong to a composite database. -Names containing `.` should be escaped. (Name: `foo.bar`) +Returned GQLSTATUS code:: +01N00 + +Returned status description:: +warn: feature deprecated. +Databases and aliases with unescaped `.` are deprecated unless to indicate that they belong to a composite database. Names containing `.` should be escaped. (Name: foo.bar) Suggestions for improvement:: If not intended for a composite database, escape the name with the character ```. @@ -1412,9 +1411,8 @@ If not intended for a composite database, escape the name with the character ``` ---- CREATE DATABASE `foo.bar` ---- - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -1423,12 +1421,9 @@ Query:: CREATE DATABASE foo.bar ---- -Returned GQLSTATUS code:: -01N00 - -Returned status description:: -warn: feature deprecated. -Databases and aliases with unescaped `.` are deprecated unless to indicate that they belong to a composite database. Names containing `.` should be escaped. (Name: foo.bar) +Description of the returned code:: +Databases and aliases with unescaped `.` are deprecated unless to indicate that they belong to a composite database. +Names containing `.` should be escaped. (Name: `foo.bar`) Suggestions for improvement:: If not intended for a composite database, escape the name with the character ```. @@ -1437,13 +1432,14 @@ If not intended for a composite database, escape the name with the character ``` ---- CREATE DATABASE `foo.bar` ---- + ====== ===== .Using differently ordered return items in a `UNION` clause [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -1454,7 +1450,11 @@ UNION RETURN 'val' as two, 'val' as one ---- -Description of the returned code:: +Returned GQLSTATUS code:: +01N00 + +Returned status description:: +warn: feature deprecated. 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. @@ -1468,9 +1468,8 @@ RETURN 'val' as one, 'val' as two UNION RETURN 'val' as one, 'val' as two ---- - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -1481,11 +1480,7 @@ UNION RETURN 'val' as two, 'val' as one ---- -Returned GQLSTATUS code:: -01N00 - -Returned status description:: -warn: feature deprecated. +Description of the returned code:: 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. @@ -1499,13 +1494,14 @@ RETURN 'val' as one, 'val' as two UNION RETURN 'val' as one, 'val' as two ---- + ====== ===== .Using the Unicode \u0085 in an unescaped identifier [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -1513,11 +1509,16 @@ Query:: ---- RETURN 1 as my\u0085identifier ---- -Description of the returned code:: -The Unicode character `\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future. To continue using it, escape the identifier by adding backticks around the identifier `my\u0085identifier`. +Returned GQLSTATUS code:: +01N00 + +Returned status description:: +warn: feature deprecated. +The Unicode character `\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future. +To continue using it, escape the identifier by adding backticks around the identifier `my\u0085identifier`. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -1525,14 +1526,9 @@ Query:: ---- RETURN 1 as my\u0085identifier ---- +Description of the returned code:: +The Unicode character `\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future. To continue using it, escape the identifier by adding backticks around the identifier `my\u0085identifier`. -Returned GQLSTATUS code:: -01N00 - -Returned status description:: -warn: feature deprecated. -The Unicode character `\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future. -To continue using it, escape the identifier by adding backticks around the identifier `my\u0085identifier`. ====== ===== @@ -1542,7 +1538,7 @@ To continue using it, escape the identifier by adding backticks around the ident .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -1575,27 +1571,6 @@ m|WARNING .Colon after the vertical bar `|:` in a relationship pattern [.tabbed-example] ===== -[.include-with-neo4j-code] -====== -Query:: -+ -[source,cypher] ----- -MATCH (a)-[:A|:B|:C]-() RETURN * ----- - -Description of the returned code:: -The semantics of using colon in the separation of alternative relationship types will change in a future version. (Please use ':A|B|C' instead) - -Suggestions for improvement:: -Remove the colon inside the relationship type expression. -+ -[source,cypher] ----- -MATCH (a)-[:A|B|C]-() RETURN * ----- - -====== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1622,35 +1597,32 @@ MATCH (a)-[:A|B|C]-() RETURN * ---- ====== -===== - -.Setting properties using a node -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Query:: + [source,cypher] ---- -MATCH (a)-[]-(b) -SET a = b +MATCH (a)-[:A|:B|:C]-() RETURN * ---- Description of the returned code:: -The use of nodes or relationships for setting properties is deprecated and will be removed in a future version. -Please use `properties()` instead. +The semantics of using colon in the separation of alternative relationship types will change in a future version. (Please use ':A|B|C' instead) Suggestions for improvement:: -Use the `properties()` function to get all properties from `b`. +Remove the colon inside the relationship type expression. + [source,cypher] ---- -MATCH (a)-[]-(b) -SET a = properties(b) +MATCH (a)-[:A|B|C]-() RETURN * ---- ====== +===== + +.Setting properties using a node +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1679,20 +1651,14 @@ SET a = properties(b) ---- ====== -===== - - -.Setting properties using a relationship -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Query:: + [source,cypher] ---- -MATCH (a)-[r]-(b) -SET a += r +MATCH (a)-[]-(b) +SET a = b ---- Description of the returned code:: @@ -1700,15 +1666,21 @@ The use of nodes or relationships for setting properties is deprecated and will Please use `properties()` instead. Suggestions for improvement:: -Use the `properties()` function to get all properties from `r`. +Use the `properties()` function to get all properties from `b`. + [source,cypher] ---- -MATCH (a)-[r]-(b) -SET a += properties(r) +MATCH (a)-[]-(b) +SET a = properties(b) ---- ====== +===== + + +.Setting properties using a relationship +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1736,35 +1708,36 @@ MATCH (a)-[r]-(b) SET a += properties(r) ---- ====== -===== - - -.Shortest path with a fixed relationship length -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Query:: + [source,cypher] ---- -MATCH (a:Start), shortestPath((a)-[r]->()) RETURN a +MATCH (a)-[r]-(b) +SET a += r ---- Description of the returned code:: -The use of `shortestPath` and `allShortestPaths` with fixed length relationships is deprecated and will be removed in a future version. -Please use a path with a length of `1 [r*1..1]` instead or a `Match` with a `limit`. +The use of nodes or relationships for setting properties is deprecated and will be removed in a future version. +Please use `properties()` instead. Suggestions for improvement:: -If the relationship length is fixed, there is no reason to search for the shortest path. -Instead, you can rewrite it to the following: +Use the `properties()` function to get all properties from `r`. + [source,cypher] ---- -MATCH (a: Start)-[r]->(b: End) RETURN b LIMIT 1 +MATCH (a)-[r]-(b) +SET a += properties(r) ---- ====== +===== + + +.Shortest path with a fixed relationship length +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1791,33 +1764,34 @@ Instead, you can rewrite it to the following: MATCH (a: Start)-[r]->(b: End) RETURN b LIMIT 1 ---- ====== -===== - -.Using a deprecated runtime option -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Query:: + [source,cypher] ---- -CYPHER runtime = interpreted MATCH (n) RETURN n +MATCH (a:Start), shortestPath((a)-[r]->()) RETURN a ---- Description of the returned code:: -The query used a deprecated runtime option. (`'runtime=interpreted'` is deprecated, please use `'runtime=slotted'` instead) +The use of `shortestPath` and `allShortestPaths` with fixed length relationships is deprecated and will be removed in a future version. +Please use a path with a length of `1 [r*1..1]` instead or a `Match` with a `limit`. Suggestions for improvement:: -Runtime `interpreted` is deprecated and another runtime is used instead. -Alternatively, you can remove the runtime option to use the default runtime. +If the relationship length is fixed, there is no reason to search for the shortest path. +Instead, you can rewrite it to the following: + [source,cypher] ---- -MATCH (n) RETURN n +MATCH (a: Start)-[r]->(b: End) RETURN b LIMIT 1 ---- ====== +===== + +.Using a deprecated runtime option +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1844,33 +1818,33 @@ Alternatively, you can remove the runtime option to use the default runtime. MATCH (n) RETURN n ---- ====== -===== - -.Using the `text-1.0` index provider when creating a text index -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Query:: + [source,cypher] ---- -CREATE TEXT INDEX FOR (n:Label) ON (n.prop) OPTIONS {indexProvider : 'text-1.0'} +CYPHER runtime = interpreted MATCH (n) RETURN n ---- Description of the returned code:: -The `text-1.0` provider for text indexes is deprecated and will be removed in a future version. -Please use `text-2.0` instead. +The query used a deprecated runtime option. (`'runtime=interpreted'` is deprecated, please use `'runtime=slotted'` instead) Suggestions for improvement:: -Update the option `indexProvider` with the value `text-2.0`. +Runtime `interpreted` is deprecated and another runtime is used instead. +Alternatively, you can remove the runtime option to use the default runtime. + [source,cypher] ---- -CREATE TEXT INDEX FOR (n:Label) ON (n.prop) OPTIONS {indexProvider : 'text-2.0'} +MATCH (n) RETURN n ---- ====== +===== + +.Using the `text-1.0` index provider when creating a text index +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Query:: @@ -1896,27 +1870,33 @@ Update the option `indexProvider` with the value `text-2.0`. CREATE TEXT INDEX FOR (n:Label) ON (n.prop) OPTIONS {indexProvider : 'text-2.0'} ---- ====== -===== - -.Using a renamed or a deprecated procedure -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== - +Query:: ++ [source,cypher] ---- -CALL unsupported.dbms.shutdown +CREATE TEXT INDEX FOR (n:Label) ON (n.prop) OPTIONS {indexProvider : 'text-1.0'} ---- Description of the returned code:: -The query used a deprecated procedure: `'unsupported.dbms.shutdown'`. +The `text-1.0` provider for text indexes is deprecated and will be removed in a future version. +Please use `text-2.0` instead. Suggestions for improvement:: -Remove the use of the deprecated procedure. -If there is a suggested replacement, update to use the replacement instead. +Update the option `indexProvider` with the value `text-2.0`. ++ +[source,cypher] +---- +CREATE TEXT INDEX FOR (n:Label) ON (n.prop) OPTIONS {indexProvider : 'text-2.0'} +---- ====== +===== + +.Using a renamed or a deprecated procedure +[.tabbed-example] +===== [.include-with-GQLSTATUS-deprecated-with-replacement] ====== [source,cypher] @@ -1947,34 +1927,27 @@ Returned status description:: warn: feature deprecated without replacement. `unsupported.dbms.shutdown` is deprecated and will be removed without a replacement. ====== -===== - -.Using id() function -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== -Query:: -+ [source,cypher] ---- -MATCH (a) -RETURN id(a) +CALL unsupported.dbms.shutdown ---- Description of the returned code:: -The query used a deprecated function: `id`. +The query used a deprecated procedure: `'unsupported.dbms.shutdown'`. Suggestions for improvement:: -Use the function `elementId()` instead. -+ -[source,cypher] ----- -MATCH (a) -RETURN elementId(a) ----- +Remove the use of the deprecated procedure. +If there is a suggested replacement, update to use the replacement instead. + ====== +===== + +.Using id() function +[.tabbed-example] +===== [.include-with-GQLSTATUS-deprecated-with-replacement] ====== Query:: @@ -2019,6 +1992,29 @@ Returned status description:: warn: feature deprecated without replacement. `id` is deprecated and will be removed without a replacement. ====== +[.include-with-neo4j-legacy-code] +====== + +Query:: ++ +[source,cypher] +---- +MATCH (a) +RETURN id(a) +---- + +Description of the returned code:: +The query used a deprecated function: `id`. + +Suggestions for improvement:: +Use the function `elementId()` instead. ++ +[source,cypher] +---- +MATCH (a) +RETURN elementId(a) +---- +====== ===== .Using an unescaped variable named 'where' in a node pattern @@ -2605,7 +2601,7 @@ END AS check .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -2632,7 +2628,7 @@ m|WARNING .Using Cypher query option `connectComponentsPlanner` [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -2640,13 +2636,15 @@ Query:: ---- CYPHER connectComponentsPlanner=greedy MATCH (a), (b) RETURN * ---- -Description of the returned code:: -The Cypher query option `connectComponentsPlanner` is deprecated and will be removed without a replacement. -The product's default behavior of using a cost-based IDP search algorithm when combining sub-plans will be kept. -For more information, see link:https://neo4j.com/docs/cypher-manual/current/query-tuning/query-options/#cypher-planner[Cypher manual -> Cypher planner]. +Returned GQLSTATUS code:: +01N02 + +Returned status description:: +warn: feature deprecated without replacement. +`connectComponentsPlanner` is deprecated and will be removed without a replacement. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -2654,13 +2652,11 @@ Query:: ---- CYPHER connectComponentsPlanner=greedy MATCH (a), (b) RETURN * ---- +Description of the returned code:: +The Cypher query option `connectComponentsPlanner` is deprecated and will be removed without a replacement. +The product's default behavior of using a cost-based IDP search algorithm when combining sub-plans will be kept. +For more information, see link:https://neo4j.com/docs/cypher-manual/current/query-tuning/query-options/#cypher-planner[Cypher manual -> Cypher planner]. -Returned GQLSTATUS code:: -01N02 - -Returned status description:: -warn: feature deprecated without replacement. -`connectComponentsPlanner` is deprecated and will be removed without a replacement. ====== ===== @@ -2670,7 +2666,7 @@ warn: feature deprecated without replacement. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -2695,7 +2691,7 @@ m|WARNING .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Request.DeprecatedFormat |Title a|The client made a request for a format which has been deprecated. @@ -2727,7 +2723,7 @@ Verify that this is the intended behavior of your query or command. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Security.CommandHasNoEffect |Title a|`` has no effect.* @@ -2755,7 +2751,7 @@ m|INFORMATION .Revoking a role from a user who does not have that role [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Command:: + @@ -2764,16 +2760,18 @@ Command:: REVOKE ROLE admin, reader FROM jane ---- -Title of the returned code:: -`REVOKE ROLE reader FROM jane` has no effect. +Returned GQLSTATUS code:: +00N71 -Description of the returned code:: -The user does not have the role. See Status Codes documentation for more information. +Returned status description:: +note: successful completion - role or privilege not assigned. +`REVOKE ROLE reader FROM jane` has no effect. +The role or privilege is not assigned. Suggestions for improvement:: Verify that this is the intended role and user. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Command:: + @@ -2782,13 +2780,11 @@ Command:: REVOKE ROLE admin, reader FROM jane ---- -Returned GQLSTATUS code:: -00N71 - -Returned status description:: -note: successful completion - role or privilege not assigned. +Title of the returned code:: `REVOKE ROLE reader FROM jane` has no effect. -The role or privilege is not assigned. + +Description of the returned code:: +The user does not have the role. See Status Codes documentation for more information. Suggestions for improvement:: Verify that this is the intended role and user. @@ -2798,8 +2794,9 @@ Verify that this is the intended role and user. .Revoking a privilege from a role that does not have that privilege [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== + Command:: + [source, cypher] @@ -2807,18 +2804,20 @@ Command:: REVOKE WRITE ON GRAPH * FROM reader ---- -Title of the returned code:: -`REVOKE DENY WRITE ON GRAPH * FROM reader` has no effect. +Returned GQLSTATUS code:: +00N71 -Description of the returned code:: -The role does not have the privilege. See Status Codes documentation for more information. +Returned status description:: +note: successful completion - role or privilege not assigned. +`REVOKE DENY WRITE ON GRAPH * FROM reader` has no effect. +The role or privilege is not assigned. Suggestions for improvement:: Verify that this is the intended privilege and role. + ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== - Command:: + [source, cypher] @@ -2826,17 +2825,14 @@ Command:: REVOKE WRITE ON GRAPH * FROM reader ---- -Returned GQLSTATUS code:: -00N71 - -Returned status description:: -note: successful completion - role or privilege not assigned. +Title of the returned code:: `REVOKE DENY WRITE ON GRAPH * FROM reader` has no effect. -The role or privilege is not assigned. + +Description of the returned code:: +The role does not have the privilege. See Status Codes documentation for more information. Suggestions for improvement:: Verify that this is the intended privilege and role. - ====== ===== @@ -2847,7 +2843,7 @@ Verify that this is the intended privilege and role. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Security.CommandHasNoEffect |Title a|`` has no effect.* @@ -2875,7 +2871,7 @@ m|INFORMATION .Granting a role to a user who already has that role [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Command:: + @@ -2883,17 +2879,20 @@ Command:: ---- GRANT ROLE admin TO john ---- -Title of the returned code:: -`GRANT ROLE admin TO john` has no effect. -Description of the returned code:: -The user already has the role. See Status Codes documentation for more information. +Returned GQLSTATUS code:: +00N70 + +Returned status description:: +note: successful completion - role or privilege already assigned. +`GRANT ROLE admin TO john` has no effect. +The role or privilege is already assigned. Suggestions for improvement:: Verify that this is the intended role and user. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Command:: + @@ -2901,14 +2900,11 @@ Command:: ---- GRANT ROLE admin TO john ---- - -Returned GQLSTATUS code:: -00N70 - -Returned status description:: -note: successful completion - role or privilege already assigned. +Title of the returned code:: `GRANT ROLE admin TO john` has no effect. -The role or privilege is already assigned. + +Description of the returned code:: +The user already has the role. See Status Codes documentation for more information. Suggestions for improvement:: Verify that this is the intended role and user. @@ -2921,7 +2917,7 @@ Verify that this is the intended role and user. // This command returns 2 notifications, one for NODES and one for RELATIONSHIPS. [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Command:: + @@ -2930,17 +2926,18 @@ Command:: GRANT TRAVERSE ON GRAPH * TO reader ---- -Title of the returned code:: -`GRANT TRAVERSE ON GRAPH * NODE * TO reader` has no effect. +Returned GQLSTATUS code:: +00N70 -Description of the returned code:: -The role already has the privilege. See Status Codes documentation for more information. +Returned status description:: +note: successful completion - role or privilege already assigned. +`GRANT TRAVERSE ON GRAPH * TO reader` has no effect. +The role or privilege is already assigned. Suggestions for improvement:: Verify that this is the intended privilege and role. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Command:: + @@ -2949,16 +2946,15 @@ Command:: GRANT TRAVERSE ON GRAPH * TO reader ---- -Returned GQLSTATUS code:: -00N70 +Title of the returned code:: +`GRANT TRAVERSE ON GRAPH * NODE * TO reader` has no effect. -Returned status description:: -note: successful completion - role or privilege already assigned. -`GRANT TRAVERSE ON GRAPH * TO reader` has no effect. -The role or privilege is already assigned. +Description of the returned code:: +The role already has the privilege. See Status Codes documentation for more information. Suggestions for improvement:: Verify that this is the intended privilege and role. + ====== ===== @@ -2970,7 +2966,7 @@ Verify that this is the intended privilege and role. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Security.ImpossibleRevokeCommand |Title a|`` has no effect.* @@ -2997,26 +2993,6 @@ m|WARNING .Revoking a non-existing role from a user [.tabbed-example] ===== -[.include-with-neo4j-code] -====== -Command:: -+ -[source, cypher] ----- -REVOKE ROLE manager, reader FROM jane ----- - -Title of the returned code:: -`REVOKE ROLE manager FROM jane` has no effect. - -Description of the returned code:: -Role does not exist. Make sure nothing is misspelled. -This notification will become an error in a future major version. -See Status Codes documentation for more information. - -Suggestions for improvement:: -Verify that this is the intended role and that it is spelled correctly. -====== [.include-with-GQLSTATUS-code] ====== Command:: @@ -3039,31 +3015,31 @@ This notification will become an error in a future major version. Suggestions for improvement:: Verify that this is the intended role and that it is spelled correctly. ====== -===== - -.Revoking a role from a non-existing user -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Command:: + [source, cypher] ---- -REVOKE ROLE reader FROM alice +REVOKE ROLE manager, reader FROM jane ---- Title of the returned code:: -`REVOKE ROLE reader FROM alice` has no effect. +`REVOKE ROLE manager FROM jane` has no effect. Description of the returned code:: -User does not exist. -Make sure nothing is misspelled. +Role does not exist. Make sure nothing is misspelled. This notification will become an error in a future major version. +See Status Codes documentation for more information. Suggestions for improvement:: -Verify that this is the intended user and that it is spelled correctly. +Verify that this is the intended role and that it is spelled correctly. ====== +===== + +.Revoking a role from a non-existing user +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== @@ -3088,32 +3064,32 @@ o Suggestions for improvement:: Verify that this is the intended user and that it is spelled correctly. ====== -===== - - -.Revoking a privilege from a non-existing role -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Command:: + [source, cypher] ---- -REVOKE GRANT WRITE ON GRAPH * FROM manager +REVOKE ROLE reader FROM alice ---- Title of the returned code:: -`REVOKE GRANT WRITE ON GRAPH * FROM manager` has no effect. +`REVOKE ROLE reader FROM alice` has no effect. Description of the returned code:: -Role does not exist. Make sure nothing is misspelled. +User does not exist. +Make sure nothing is misspelled. This notification will become an error in a future major version. -See Status Codes documentation for more information. Suggestions for improvement:: -Verify that this is the intended role and that it is spelled correctly. +Verify that this is the intended user and that it is spelled correctly. ====== +===== + + +.Revoking a privilege from a non-existing role +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== @@ -3137,31 +3113,31 @@ This notification will become an error in a future major version. Suggestions for improvement:: Verify that this is the intended role and that it is spelled correctly. ====== -===== - -.Revoking a privilege on a non-existing graph from a role -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Command:: + [source, cypher] ---- -REVOKE GRANT WRITE ON GRAPH neo3j FROM editor +REVOKE GRANT WRITE ON GRAPH * FROM manager ---- Title of the returned code:: -`REVOKE GRANT WRITE ON GRAPH neo3j FROM editor` has no effect. +`REVOKE GRANT WRITE ON GRAPH * FROM manager` has no effect. Description of the returned code:: -Database `neo3j` does not exist. Make sure nothing is misspelled. +Role does not exist. Make sure nothing is misspelled. This notification will become an error in a future major version. See Status Codes documentation for more information. Suggestions for improvement:: -Verify that this is the intended graph and that it is spelled correctly. +Verify that this is the intended role and that it is spelled correctly. ====== +===== + +.Revoking a privilege on a non-existing graph from a role +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Command:: @@ -3184,22 +3160,17 @@ This notification will become an error in a future major version. Suggestions for improvement:: Verify that this is the intended graph and that it is spelled correctly. ====== -===== - -.Revoking a privilege on a non-existing database from a role -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Command:: + [source, cypher] ---- -REVOKE GRANT ACCESS ON DATABASE neo3j FROM editor +REVOKE GRANT WRITE ON GRAPH neo3j FROM editor ---- Title of the returned code:: -`REVOKE GRANT ACCESS ON DATABASE neo3j FROM editor` has no effect. +`REVOKE GRANT WRITE ON GRAPH neo3j FROM editor` has no effect. Description of the returned code:: Database `neo3j` does not exist. Make sure nothing is misspelled. @@ -3207,8 +3178,13 @@ This notification will become an error in a future major version. See Status Codes documentation for more information. Suggestions for improvement:: -Verify that this is the intended database and that it is spelled correctly. +Verify that this is the intended graph and that it is spelled correctly. ====== +===== + +.Revoking a privilege on a non-existing database from a role +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Command:: @@ -3232,41 +3208,32 @@ Suggestions for improvement:: Verify that this is the intended database and that it is spelled correctly. ====== -===== - - -.Revoking a privilege from a role with wildcard graph parameter -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== -Parameter:: -+ -[source, javascript] ----- -{ - "graph": "*" -} ----- Command:: + [source, cypher] ---- -REVOKE GRANT CREATE ON GRAPH $graph FROM PUBLIC +REVOKE GRANT ACCESS ON DATABASE neo3j FROM editor ---- Title of the returned code:: -`REVOKE GRANT CREATE ON GRAPH $graph FROM PUBLIC` has no effect. +`REVOKE GRANT ACCESS ON DATABASE neo3j FROM editor` has no effect. Description of the returned code:: -Parameterized database and graph names do not support wildcards. -Make sure nothing is misspelled. +Database `neo3j` does not exist. Make sure nothing is misspelled. This notification will become an error in a future major version. See Status Codes documentation for more information. Suggestions for improvement:: -Use `GRAPH *` without the parameter to revoke the privilege on all graphs. +Verify that this is the intended database and that it is spelled correctly. ====== +===== + + +.Revoking a privilege from a role with wildcard graph parameter +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== Parameter:: @@ -3299,30 +3266,25 @@ Use `GRAPH *` without the parameter to revoke the privilege on all graphs. ====== -===== - -.Revoking a privilege from a role with a wildcard database parameter -[.tabbed-example] -===== -[.include-with-neo4j-code] +[.include-with-neo4j-legacy-code] ====== Parameter:: + [source, javascript] ---- { - "database": "*" + "graph": "*" } ---- Command:: + [source, cypher] ---- -REVOKE GRANT ACCESS ON DATABASE $database FROM PUBLIC +REVOKE GRANT CREATE ON GRAPH $graph FROM PUBLIC ---- Title of the returned code:: -`REVOKE GRANT ACCESS ON DATABASE $database FROM PUBLIC` has no effect. +`REVOKE GRANT CREATE ON GRAPH $graph FROM PUBLIC` has no effect. Description of the returned code:: Parameterized database and graph names do not support wildcards. @@ -3331,8 +3293,13 @@ This notification will become an error in a future major version. See Status Codes documentation for more information. Suggestions for improvement:: -Use `DATABASE *` without the parameter to revoke the privilege on all databases. +Use `GRAPH *` without the parameter to revoke the privilege on all graphs. ====== +===== + +.Revoking a privilege from a role with a wildcard database parameter +[.tabbed-example] +===== [.include-with-GQLSTATUS-code] ====== @@ -3364,6 +3331,35 @@ This notification will become an error in a future major version. Suggestions for improvement:: Use `DATABASE *` without the parameter to revoke the privilege on all databases. +====== +[.include-with-neo4j-legacy-code] +====== +Parameter:: ++ +[source, javascript] +---- +{ + "database": "*" +} +---- +Command:: ++ +[source, cypher] +---- +REVOKE GRANT ACCESS ON DATABASE $database FROM PUBLIC +---- + +Title of the returned code:: +`REVOKE GRANT ACCESS ON DATABASE $database FROM PUBLIC` has no effect. + +Description of the returned code:: +Parameterized database and graph names do not support wildcards. +Make sure nothing is misspelled. +This notification will become an error in a future major version. +See Status Codes documentation for more information. + +Suggestions for improvement:: +Use `DATABASE *` without the parameter to revoke the privilege on all databases. ====== ===== @@ -3600,7 +3596,7 @@ Topology notifications provide additional information related to managing databa .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Cluster.ServerAlreadyEnabled |Title a| `` has no effect. @@ -3625,7 +3621,7 @@ m|INFORMATION .Enabling an already enabled server [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Command:: + @@ -3634,12 +3630,17 @@ Command:: ENABLE SERVER "123e4567-e89b-12d3-a456-426614174000" ---- -Description of the returned code:: +Returned GQLSTATUS code:: +00N80 + +Returned status description:: +note: successful completion - server already enabled. +`ENABLE SERVER` has no effect. Server `123e4567-e89b-12d3-a456-426614174000` is already enabled. Verify that this is the intended server. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Command:: + @@ -3648,12 +3649,7 @@ Command:: ENABLE SERVER "123e4567-e89b-12d3-a456-426614174000" ---- -Returned GQLSTATUS code:: -00N80 - -Returned status description:: -note: successful completion - server already enabled. -`ENABLE SERVER` has no effect. +Description of the returned code:: Server `123e4567-e89b-12d3-a456-426614174000` is already enabled. Verify that this is the intended server. @@ -3666,7 +3662,7 @@ Verify that this is the intended server. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Cluster.ServerAlreadyCordoned |Title a| `` has no effect. @@ -3691,7 +3687,7 @@ m|INFORMATION .Cordoning an already cordoned server [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Command:: + @@ -3700,12 +3696,17 @@ Command:: CORDON SERVER "123e4567-e89b-12d3-a456-426614174000" ---- -Description of the returned code:: +Returned GQLSTATUS code:: +00N81 + +Returned status description:: +note: successful completion - server already cordoned. +`CORDON SERVER` has no effect. Server `123e4567-e89b-12d3-a456-426614174000` is already cordoned. Verify that this is the intended server. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Command:: + @@ -3714,12 +3715,7 @@ Command:: CORDON SERVER "123e4567-e89b-12d3-a456-426614174000" ---- -Returned GQLSTATUS code:: -00N81 - -Returned status description:: -note: successful completion - server already cordoned. -`CORDON SERVER` has no effect. +Description of the returned code:: Server `123e4567-e89b-12d3-a456-426614174000` is already cordoned. Verify that this is the intended server. @@ -3732,7 +3728,7 @@ Verify that this is the intended server. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Cluster.NoDatabasesReallocated |Title a| `` has no effect. @@ -3756,7 +3752,7 @@ m|INFORMATION .Reallocating databases resulted in no allocation changes [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Command:: + @@ -3765,9 +3761,14 @@ Command:: REALLOCATE DATABASES ---- -Description of the returned code:: -No databases were reallocated. No better allocation is currently possible. +Returned GQLSTATUS code:: +00N82 +Returned status description:: +note: successful completion - no databases reallocated. +`REALLOCATE DATABASES` has no effect. +No databases were reallocated. +No better allocation is currently possible. Example scenarios:: **Scenario 1:** The cluster is already balanced. @@ -3778,7 +3779,7 @@ For example, when there are three servers, each hosting databases `foo` and `bar For example, assuming server 1 hosts databases `foo` and `bar`, server 2 hosts only `foo`, and server 3 hosts no databases. Then, a better allocation would move `foo` from server 1 to server 3, but if server 3 has the constraint `deniedDatabases:['foo']}`, then the cluster is already balanced subject to this constraint. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Command:: + @@ -3787,14 +3788,9 @@ Command:: REALLOCATE DATABASES ---- -Returned GQLSTATUS code:: -00N82 +Description of the returned code:: +No databases were reallocated. No better allocation is currently possible. -Returned status description:: -note: successful completion - no databases reallocated. -`REALLOCATE DATABASES` has no effect. -No databases were reallocated. -No better allocation is currently possible. Example scenarios:: **Scenario 1:** The cluster is already balanced. @@ -3816,7 +3812,7 @@ For example, `CREATE DATABASE`, `ALTER DATABASE`, `DEALLOCATE DATABASES FROM SER .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Cluster.CordonedServersExistedDuringAllocation |Title a| Cordoned servers existed when making an allocation decision. @@ -3840,7 +3836,7 @@ m|INFORMATION .Cordoned servers existed during an allocation decision [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== The example assumes that you have a cluster with three servers, of which server `123e4567-e89b-12d3-a456-426614174000` is cordoned using the `dbms.cluster.cordonServer` procedure. Then the below command will return this notification. @@ -3851,10 +3847,16 @@ Command:: CREATE DATABASE foo TOPOLOGY 2 PRIMARIES ---- -Description of the returned code:: -Server(s) `123e4567-e89b-12d3-a456-426614174000` are cordoned. This can impact allocation decisions. +Returned GQLSTATUS code:: +00N83 + +Returned status description:: +note: successful completion - cordoned servers existed during allocation. +Cordoned servers existed when making an allocation decision. +Server(s) `123e4567-e89b-12d3-a456-426614174000` are cordoned. +This can impact allocation decisions. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== The example assumes that you have a cluster with three servers, of which server `123e4567-e89b-12d3-a456-426614174000` is cordoned using the `dbms.cluster.cordonServer` procedure. Then the below command will return this notification. @@ -3865,14 +3867,8 @@ Command:: CREATE DATABASE foo TOPOLOGY 2 PRIMARIES ---- -Returned GQLSTATUS code:: -00N83 - -Returned status description:: -note: successful completion - cordoned servers existed during allocation. -Cordoned servers existed when making an allocation decision. -Server(s) `123e4567-e89b-12d3-a456-426614174000` are cordoned. -This can impact allocation decisions. +Description of the returned code:: +Server(s) `123e4567-e89b-12d3-a456-426614174000` are cordoned. This can impact allocation decisions. ====== ===== @@ -3883,7 +3879,7 @@ This can impact allocation decisions. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Cluster.RequestedTopologyMatchedCurrentTopology |Title a| `` has no effect. @@ -3908,7 +3904,7 @@ m|INFORMATION .Requested topology matched current topology [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== The example assumes that you have a cluster with three servers and a database `foo` with a topology of two primaries and one secondary. @@ -3919,10 +3915,17 @@ Command:: ALTER DATABASE foo SET TOPOLOGY 2 PRIMARIES 1 SECONDARY ---- -Description of the returned code:: -The requested topology matched the current topology. No allocations were changed. +Returned GQLSTATUS code:: +00N84 + +Returned status description:: +note: successful completion - requested topology matched current topology. +`ALTER DATABASE` has no effect. +The requested topology matched the current topology. +No allocations were changed. + ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== The example assumes that you have a cluster with three servers and a database `foo` with a topology of two primaries and one secondary. @@ -3933,15 +3936,8 @@ Command:: ALTER DATABASE foo SET TOPOLOGY 2 PRIMARIES 1 SECONDARY ---- -Returned GQLSTATUS code:: -00N84 - -Returned status description:: -note: successful completion - requested topology matched current topology. -`ALTER DATABASE` has no effect. -The requested topology matched the current topology. -No allocations were changed. - +Description of the returned code:: +The requested topology matched the current topology. No allocations were changed. ====== ===== @@ -3956,7 +3952,7 @@ Schema notifications provide additional information related to indexes and const .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Schema.IndexOrConstraintAlreadyExists |Title a|`` has no effect. @@ -3981,7 +3977,7 @@ m|INFORMATION .Creating an index when an equivalent index already exists [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Given a range index on `(:Label \{property})` named `existingRangeIndex`. @@ -3992,14 +3988,16 @@ Command:: CREATE INDEX labelProperyRangeIndex IF NOT EXISTS FOR (n:Label) ON (n.property) ---- -Title of the returned code:: -`CREATE RANGE INDEX labelProperyRangeIndex IF NOT EXISTS FOR (e:Label) ON (e.property)` has no effect. +Returned GQLSTATUS code:: +00NA0 -Full description of the returned code:: +Returned status description:: +note: successful completion - index or constraint already exists. +`CREATE RANGE INDEX labelProperyRangeIndex IF NOT EXISTS FOR (e:Label) ON (e.property)` has no effect. `RANGE INDEX existingRangeIndex FOR (e:Label) ON (e.property)` already exists. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Given a range index on `(:Label \{property})` named `existingRangeIndex`. @@ -4010,12 +4008,10 @@ Command:: CREATE INDEX labelProperyRangeIndex IF NOT EXISTS FOR (n:Label) ON (n.property) ---- -Returned GQLSTATUS code:: -00NA0 - -Returned status description:: -note: successful completion - index or constraint already exists. +Title of the returned code:: `CREATE RANGE INDEX labelProperyRangeIndex IF NOT EXISTS FOR (e:Label) ON (e.property)` has no effect. + +Full description of the returned code:: `RANGE INDEX existingRangeIndex FOR (e:Label) ON (e.property)` already exists. ====== @@ -4024,7 +4020,7 @@ note: successful completion - index or constraint already exists. .Creating an index when another unrelated index using that name already exists [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Given a range index on `(:Label \{property})` named `myIndex`. @@ -4035,10 +4031,12 @@ Command:: CREATE TEXT INDEX myIndex IF NOT EXISTS FOR ()-[r:REL_TYPE]-() ON (r.property) ---- -Title of the returned code:: -`CREATE TEXT INDEX myIndex IF NOT EXISTS FOR ()-[e:REL_TYPE]-() ON (e.property)` has no effect. +Returned GQLSTATUS code:: +00NA0 -Full description of the returned code:: +Returned status description:: +note: successful completion - index or constraint already exists. +`CREATE TEXT INDEX myIndex IF NOT EXISTS FOR ()-[e:REL_TYPE]-() ON (e.property)` has no effect. `RANGE INDEX myIndex FOR (e:Label) ON (e.property)` already exists. Suggestions for improvement:: @@ -4050,7 +4048,7 @@ CREATE TEXT INDEX myIndex2 IF NOT EXISTS FOR ()-[r:REL_TYPE]-() ON (r.property) ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Given a range index on `(:Label \{property})` named `myIndex`. @@ -4061,12 +4059,10 @@ Command:: CREATE TEXT INDEX myIndex IF NOT EXISTS FOR ()-[r:REL_TYPE]-() ON (r.property) ---- -Returned GQLSTATUS code:: -00NA0 - -Returned status description:: -note: successful completion - index or constraint already exists. +Title of the returned code:: `CREATE TEXT INDEX myIndex IF NOT EXISTS FOR ()-[e:REL_TYPE]-() ON (e.property)` has no effect. + +Full description of the returned code:: `RANGE INDEX myIndex FOR (e:Label) ON (e.property)` already exists. Suggestions for improvement:: @@ -4083,7 +4079,7 @@ CREATE TEXT INDEX myIndex2 IF NOT EXISTS FOR ()-[r:REL_TYPE]-() ON (r.property) .Creating a constraint when an identical constraint already exists [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Given a node key constraint on `(:Label \{property})` named `nodeKeyLabelPropertyConstraint`. @@ -4094,14 +4090,16 @@ Command:: CREATE CONSTRAINT nodeKeyLabelPropertyConstraint IF NOT EXISTS FOR (n:Label) REQUIRE (n.property) IS NODE KEY ---- -Title of the returned code:: -`CREATE CONSTRAINT nodeKeyLabelPropertyConstraint IF NOT EXISTS FOR (e:Label) REQUIRE (e.property) IS NODE KEY` has no effect. +Returned GQLSTATUS code:: +00NA0 -Full description of the returned code:: +Returned status description:: +note: successful completion - index or constraint already exists. +`CREATE CONSTRAINT nodeKeyLabelPropertyConstraint IF NOT EXISTS FOR (e:Label) REQUIRE (e.property) IS NODE KEY` has no effect. `CONSTRAINT nodeKeyLabelPropertyConstraint FOR (e:Label) REQUIRE (e.property) IS NODE KEY` already exists. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Given a node key constraint on `(:Label \{property})` named `nodeKeyLabelPropertyConstraint`. @@ -4112,12 +4110,10 @@ Command:: CREATE CONSTRAINT nodeKeyLabelPropertyConstraint IF NOT EXISTS FOR (n:Label) REQUIRE (n.property) IS NODE KEY ---- -Returned GQLSTATUS code:: -00NA0 - -Returned status description:: -note: successful completion - index or constraint already exists. +Title of the returned code:: `CREATE CONSTRAINT nodeKeyLabelPropertyConstraint IF NOT EXISTS FOR (e:Label) REQUIRE (e.property) IS NODE KEY` has no effect. + +Full description of the returned code:: `CONSTRAINT nodeKeyLabelPropertyConstraint FOR (e:Label) REQUIRE (e.property) IS NODE KEY` already exists. ====== @@ -4127,7 +4123,7 @@ note: successful completion - index or constraint already exists. .Creating a constraint when another unrelated constraint using that name already exists [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Given a node key constraint on `(:Label \{property})` named `myConstraint`. @@ -4138,10 +4134,12 @@ Command:: CREATE CONSTRAINT myConstraint IF NOT EXISTS FOR (n:Label2) REQUIRE (n.property2) IS NOT NULL ---- -Title of the returned code:: -`CREATE CONSTRAINT myConstraint IF NOT EXISTS FOR (e:Label2) REQUIRE (e.property2) IS NOT NULL` has no effect. +Returned GQLSTATUS code:: +00NA0 -Full description of the returned code:: +Returned status description:: +note: successful completion - index or constraint already exists. +`CREATE CONSTRAINT myConstraint IF NOT EXISTS FOR (e:Label2) REQUIRE (e.property2) IS NOT NULL` has no effect. `CONSTRAINT myConstraint FOR (e:Label) REQUIRE (e.property) IS NODE KEY` already exists. Suggestions for improvement:: @@ -4153,7 +4151,7 @@ CREATE CONSTRAINT myConstraint2 IF NOT EXISTS FOR (n:Label2) REQUIRE (n.property ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Given a node key constraint on `(:Label \{property})` named `myConstraint`. @@ -4164,12 +4162,10 @@ Command:: CREATE CONSTRAINT myConstraint IF NOT EXISTS FOR (n:Label2) REQUIRE (n.property2) IS NOT NULL ---- -Returned GQLSTATUS code:: -00NA0 - -Returned status description:: -note: successful completion - index or constraint already exists. +Title of the returned code:: `CREATE CONSTRAINT myConstraint IF NOT EXISTS FOR (e:Label2) REQUIRE (e.property2) IS NOT NULL` has no effect. + +Full description of the returned code:: `CONSTRAINT myConstraint FOR (e:Label) REQUIRE (e.property) IS NODE KEY` already exists. Suggestions for improvement:: @@ -4189,7 +4185,7 @@ CREATE CONSTRAINT myConstraint2 IF NOT EXISTS FOR (n:Label2) REQUIRE (n.property .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Schema.IndexOrConstraintDoesNotExist |Title a|`` has no effect. @@ -4210,9 +4206,8 @@ m|INFORMATION .Attempting to drop a non-existing index [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== - Command:: + [source, cypher] @@ -4220,18 +4215,21 @@ Command:: DROP INDEX nonExistingIndex IF EXISTS ---- -Title of the returned code:: -`DROP INDEX nonExistingIndex IF EXISTS` has no effect. +Returned GQLSTATUS code:: +00NA1 -Full description of the returned code:: +Returned status description:: +note: successful completion - index or constraint does not exist. +`DROP INDEX nonExistingIndex IF EXISTS` has no effect. `nonExistingIndex` does not exist. Suggestions for improvement:: Verify that this is the intended index and that it is spelled correctly. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== + Command:: + [source, cypher] @@ -4239,12 +4237,10 @@ Command:: DROP INDEX nonExistingIndex IF EXISTS ---- -Returned GQLSTATUS code:: -00NA1 - -Returned status description:: -note: successful completion - index or constraint does not exist. +Title of the returned code:: `DROP INDEX nonExistingIndex IF EXISTS` has no effect. + +Full description of the returned code:: `nonExistingIndex` does not exist. Suggestions for improvement:: @@ -4256,9 +4252,8 @@ Verify that this is the intended index and that it is spelled correctly. .Attempting to drop a non-existing constraint [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== - Command:: + [source, cypher] @@ -4266,18 +4261,21 @@ Command:: DROP CONSTRAINT nonExistingConstraint IF EXISTS ---- -Title of the returned code:: -`DROP CONSTRAINT nonExistingConstraint IF EXISTS` has no effect. +Returned GQLSTATUS code:: +00NA1 -Full description of the returned code:: +Returned status description:: +note: successful completion - index or constraint does not exist. +`DROP CONSTRAINT nonExistingConstraint IF EXISTS` has no effect. `nonExistingConstraint` does not exist. Suggestions for improvement:: Verify that this is the intended constraint and that it is spelled correctly. ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== + Command:: + [source, cypher] @@ -4285,12 +4283,10 @@ Command:: DROP CONSTRAINT nonExistingConstraint IF EXISTS ---- -Returned GQLSTATUS code:: -00NA1 - -Returned status description:: -note: successful completion - index or constraint does not exist. +Title of the returned code:: `DROP CONSTRAINT nonExistingConstraint IF EXISTS` has no effect. + +Full description of the returned code:: `nonExistingConstraint` does not exist. Suggestions for improvement:: @@ -4310,7 +4306,7 @@ Verify that this is the intended constraint and that it is spelled correctly. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.SubqueryVariableShadowing |Title a|Variable in subquery is shadowing a variable with the same name from the outer scope. @@ -4334,7 +4330,7 @@ m|INFORMATION .Shadowing of a variable from the outer scope [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -4348,9 +4344,13 @@ CALL { RETURN * ---- -Description of the returned code:: -Variable in subquery is shadowing a variable with the same name from the outer scope. -If you want to use that variable instead, it must be imported into the subquery using importing `WITH` clause. (the shadowing variable is: `n`) +Returned GQLSTATUS code:: +03N60 + +Returned status description:: +info: subquery variable shadowing. +The variable `n` in the subquery uses the same name as a variable from the outer query. +Use `WITH n` in the subquery to import the one from the outer scope unless you want it to be a new variable. Suggestions for improvement:: If the intended behavior of the query is for the variable in the subquery to be a new variable, then nothing needs to be done. @@ -4367,7 +4367,7 @@ CALL { RETURN * ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -4381,13 +4381,9 @@ CALL { RETURN * ---- -Returned GQLSTATUS code:: -03N60 - -Returned status description:: -info: subquery variable shadowing. -The variable `n` in the subquery uses the same name as a variable from the outer query. -Use `WITH n` in the subquery to import the one from the outer scope unless you want it to be a new variable. +Description of the returned code:: +Variable in subquery is shadowing a variable with the same name from the outer scope. +If you want to use that variable instead, it must be imported into the subquery using importing `WITH` clause. (the shadowing variable is: `n`) Suggestions for improvement:: If the intended behavior of the query is for the variable in the subquery to be a new variable, then nothing needs to be done. @@ -4412,7 +4408,7 @@ RETURN * .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.RedundantOptionalProcedure |Title a|The use of `OPTIONAL` is redundant when the procedure calls a void procedure. @@ -4433,7 +4429,7 @@ m|INFORMATION .Redundant use of `OPTIONAL` in a procedure call [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -4441,9 +4437,11 @@ Query:: ---- OPTIONAL CALL db.createLabel("A") ---- +Returned GQLSTATUS code:: +03N61 -Description of the returned code:: -The use of `OPTIONAL` is redundant as `CALL db.createLabel` is a void procedure. +Returned status description:: +info: redundant optional procedure. The use of `OPTIONAL` is redundant as `CALL db.createLabel` is a void procedure. Suggestions for improvement:: If the intended behavior of the query is to use a void procedure, the `OPTIONAL` keyword can be removed without impacting the query. @@ -4453,7 +4451,7 @@ If the intended behavior of the query is to use a void procedure, the `OPTIONAL` CALL db.createLabel("A") ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -4461,11 +4459,9 @@ Query:: ---- OPTIONAL CALL db.createLabel("A") ---- -Returned GQLSTATUS code:: -03N61 -Returned status description:: -info: redundant optional procedure. The use of `OPTIONAL` is redundant as `CALL db.createLabel` is a void procedure. +Description of the returned code:: +The use of `OPTIONAL` is redundant as `CALL db.createLabel` is a void procedure. Suggestions for improvement:: If the intended behavior of the query is to use a void procedure, the `OPTIONAL` keyword can be removed without impacting the query. @@ -4483,7 +4479,7 @@ CALL db.createLabel("A") .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.RedundantOptionalSubquery |Title a|The use of `OPTIONAL` is redundant when `CALL` is a unit subquery. @@ -4504,7 +4500,7 @@ m|INFORMATION .Redundant use of `OPTIONAL` in a `CALL` subquery [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -4516,8 +4512,11 @@ OPTIONAL CALL (x) { } ---- +Returned GQLSTATUS code:: +03N62 + Description of the returned code:: -Optional is redundant in the case of a unit subquery. The use of `OPTIONAL` on unit subqueries have no effect and can be removed. +info: redundant optional subquery. The use of `OPTIONAL` is redundant as `CALL` is a unit subquery. Suggestions for improvement:: If the intended behavior of the query is for the subquery not to return any values, the `OPTIONAL` keyword can be removed without impacting the query. @@ -4530,7 +4529,7 @@ CALL (x) { } ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -4542,11 +4541,8 @@ OPTIONAL CALL (x) { } ---- -Returned GQLSTATUS code:: -03N62 - Description of the returned code:: -info: redundant optional subquery. The use of `OPTIONAL` is redundant as `CALL` is a unit subquery. +Optional is redundant in the case of a unit subquery. The use of `OPTIONAL` on unit subqueries have no effect and can be removed. Suggestions for improvement:: If the intended behavior of the query is for the subquery not to return any values, the `OPTIONAL` keyword can be removed without impacting the query. @@ -4567,7 +4563,7 @@ CALL (x) { .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.ParameterNotProvided |Title a|The statement refers to a parameter that was not provided in the request. @@ -4592,7 +4588,7 @@ m|WARNING .Using an `EXPLAIN` query with parameters without providing them [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -4602,15 +4598,18 @@ EXPLAIN WITH $param as param RETURN param ---- -Description of the returned code:: -Did not supply query with enough parameters. -The produced query plan will not be cached and is not executable without `EXPLAIN`. (Missing parameters: `param`) +Returned GQLSTATUS code:: +01N60 + +Returned status description:: +warn: parameter missing. +The query plan cannot be cached and is not executable without `EXPLAIN` due to the undefined parameter(s) `{ $param }`. +Provide the parameter(s). Suggestions for improvement:: Provide the parameter to be able to cache the plan. - ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -4620,16 +4619,13 @@ EXPLAIN WITH $param as param RETURN param ---- -Returned GQLSTATUS code:: -01N60 - -Returned status description:: -warn: parameter missing. -The query plan cannot be cached and is not executable without `EXPLAIN` due to the undefined parameter(s) `{ $param }`. -Provide the parameter(s). +Description of the returned code:: +Did not supply query with enough parameters. +The produced query plan will not be cached and is not executable without `EXPLAIN`. (Missing parameters: `param`) Suggestions for improvement:: Provide the parameter to be able to cache the plan. + ====== ===== @@ -4640,7 +4636,7 @@ Provide the parameter to be able to cache the plan. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Procedure.ProcedureWarning |Title a|The query used a procedure that generated a warning. @@ -4669,7 +4665,7 @@ When matching on a relationship type expression that can never be satisfied, for .Notification category details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.UnsatisfiableRelationshipTypeExpression |Title a|The query contains a relationship type expression that cannot be satisfied. @@ -4692,17 +4688,6 @@ m|WARNING .Matching on a relationship type expression that can never be satisfied [.tabbed-example] ===== -[.include-with-neo4j-code] -====== -Query:: -+ -[source,cypher] ----- -MATCH ()-[r:R1&R2]->() RETURN r ----- -Description of the returned code:: -Relationship type expression cannot possibly be satisfied. (`R1&R2` can never be fulfilled by any relationship. Relationships must have exactly one type.) -====== [.include-with-GQLSTATUS-code] ====== Query:: @@ -4719,6 +4704,17 @@ Returned status description:: warn: unsatisfiable relationship type expression. The expression `R1&R2` cannot be satisfied because relationships must have exactly one type. ====== +[.include-with-neo4j-legacy-code] +====== +Query:: ++ +[source,cypher] +---- +MATCH ()-[r:R1&R2]->() RETURN r +---- +Description of the returned code:: +Relationship type expression cannot possibly be satisfied. (`R1&R2` can never be fulfilled by any relationship. Relationships must have exactly one type.) +====== ===== [role=label--new-5.5] @@ -4728,7 +4724,7 @@ The expression `R1&R2` cannot be satisfied because relationships must have exact .Notification category details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Statement.RepeatedRelationshipReference |Title a|The query returns no results because a relationship variable is bound more than once. @@ -4753,7 +4749,7 @@ m|WARNING .Binding a relationship variable more than once [.tabbed-example] ===== -[.include-with-neo4j-code] +[.include-with-GQLSTATUS-code] ====== Query:: + @@ -4761,8 +4757,13 @@ Query:: ---- MATCH (:A)-[r]->(), ()-[r]->(:B) RETURN r ---- -Description of the returned code:: -A relationship is referenced more than once in the query, which leads to no results because relationships must not occur more than once in each result. (Relationship `r` was repeated) + +Returned GQLSTATUS code:: +01N63 + +Returned status description:: +warn: repeated relationship reference. +`r` is repeated in `(:A)-[r]->(), ()-[r]->(:B)`, which leads to no results. Suggestions for improvement:: Use one pattern to match all relationships that start with a node with the label `A` and end with a node with the label `B`: @@ -4772,7 +4773,7 @@ Use one pattern to match all relationships that start with a node with the label MATCH (:A)-[r]->(:B) RETURN r ---- ====== -[.include-with-GQLSTATUS-code] +[.include-with-neo4j-legacy-code] ====== Query:: + @@ -4780,13 +4781,8 @@ Query:: ---- MATCH (:A)-[r]->(), ()-[r]->(:B) RETURN r ---- - -Returned GQLSTATUS code:: -01N63 - -Returned status description:: -warn: repeated relationship reference. -`r` is repeated in `(:A)-[r]->(), ()-[r]->(:B)`, which leads to no results. +Description of the returned code:: +A relationship is referenced more than once in the query, which leads to no results because relationships must not occur more than once in each result. (Relationship `r` was repeated) Suggestions for improvement:: Use one pattern to match all relationships that start with a node with the label `A` and end with a node with the label `B`: @@ -4801,18 +4797,6 @@ MATCH (:A)-[r]->(:B) RETURN r .Binding a variable-length relationship variable more than once (when run on version 5.6 or newer) [.tabbed-example] ===== -[.include-with-neo4j-code] -====== -Query:: -+ -[source,cypher] ----- -MATCH ()-[r*]->()<-[r*]-() RETURN count(*) AS count ----- -Description of the returned code:: -A variable-length relationship variable is bound more than once, which leads to no results because relationships must not occur more than once in each result. (Relationship r was repeated) -====== - [.include-with-GQLSTATUS-code] ====== Query:: @@ -4829,4 +4813,15 @@ Returned status description:: warn: repeated relationship reference. `r` is repeated in `()-[r*]->()<-[r*]-()`, which leads to no results. ====== +[.include-with-neo4j-legacy-code] +====== +Query:: ++ +[source,cypher] +---- +MATCH ()-[r*]->()<-[r*]-() RETURN count(*) AS count +---- +Description of the returned code:: +A variable-length relationship variable is bound more than once, which leads to no results because relationships must not occur more than once in each result. (Relationship r was repeated) +====== ===== diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 1fd25f28..42c89a7c 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -9,38 +9,9 @@ The driver receives these notifications and sends them to the client, which disp From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API. The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. -This page describes both the Neo4j Notification and the GQL-status object frameworks, how they are structured, the objects they provide for notifications, and how to interpret them. +This page describes both the GQL-status object and the Neo4j Notification frameworks, how they are structured, the objects they provide for notifications, and how to interpret them. It also explains the server notification grouping and filtering, the notification internals, and the server-driver compatibility for both the Notification and GqlStatusObject APIs. -[[neo4j-notification-object]] -== Neo4j notification object - -The Neo4j notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. -Depending on the application, some of the fields from the notification object might not be visible. - -The notification object consists of the following fields: - -.Neo4j notification object -[cols="<1s,<4"] -|=== -|Neo4j code -a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. -|Title -a|The title of the Neo4j status code. -|Description -a|The description of the specific notification. -|Severity level -a|The severity can be one of the following: - -- `WARNING`: There might be a problem with your query. Please, take a look. -- `INFORMATION`: The query is correct, but this information can still be useful. -|Category -a|The category of the notification. -|Position -a|The position, given by row and column, where the notification is relevant in the query text. -|=== - - [role=label--version-5.23] [[gqlstatus-notification-object]] == GQL-status notification object @@ -177,6 +148,34 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their |=== +[[neo4j-notification-object]] +== Neo4j notification object + +The Neo4j notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. +Depending on the application, some of the fields from the notification object might not be visible. + +The notification object consists of the following fields: + +.Neo4j notification object +[cols="<1s,<4"] +|=== +|Neo4j code +a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. +|Title +a|The title of the Neo4j status code. +|Description +a|The description of the specific notification. +|Severity level +a|The severity can be one of the following: + +- `WARNING`: There might be a problem with your query. Please, take a look. +- `INFORMATION`: The query is correct, but this information can still be useful. +|Category +a|The category of the notification. +|Position +a|The position, given by row and column, where the notification is relevant in the query text. +|=== + [[notification-grouping-and-filtering]] == Server notification grouping and filtering From b1ce2ddb7fbdc7e767e36ae9156efe1528f4a150 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 1 Nov 2024 13:49:40 +0000 Subject: [PATCH 02/29] add info about deprecated notification api and swap the code examples --- modules/ROOT/pages/draft.adoc | 11 ++++++++++- .../pages/notifications/all-notifications.adoc | 6 +++--- modules/ROOT/pages/notifications/index.adoc | 18 +++++++++++------- 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/draft.adoc b/modules/ROOT/pages/draft.adoc index c6021a7f..f561c18e 100644 --- a/modules/ROOT/pages/draft.adoc +++ b/modules/ROOT/pages/draft.adoc @@ -20,4 +20,13 @@ The ultimate goal is to have a 1-1 mapping between a GQLSTATUS code and a specif If a Neo4j error matches a standard-defined condition and subcondition, then the standard-defined GQLSTATUS code should be used for that error. For instance, (Neo.ClientError.Statement.ArithmeticError, ArithmeticException, “/by zero”) matches the “data exception” condition and “division by zero” subcondition in GQL (i.e., 22012 GQLSTATUS code). -error: data exception - string data, right truncation \ No newline at end of file +error: data exception - string data, right truncation + + + +Processing of GQL-requests can cause various conditions to be raised. Each such condition is identified by a unique code called GQLSTATUS, which is a character string that always includes a class code that specifies the principle category to which the condition belongs. It may also include a subclass code that specifies additional information about the reason for raising the condition. The exact format of GQLSTATUS codes is specified in Subclause 23.1, “GQLSTATUS”. +For example, the GQLSTATUS '22003' identifies the exception condition “data exception — numeric value out of range”. +The GQLSTATUS codes assigned by this document to conditions are stable and can be depended on to remain constant. +There are two types of conditions: +— completion conditions. +— exception conditions. diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 9d927abb..15cab4a3 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -3,7 +3,7 @@ [[listOfNnotifications]] = List of all server notification codes -The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and the legacy Neo4j codes, along with some scenarios and their possible solutions. +The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and Neo4j legacy codes, along with some scenarios and their possible solutions. * <<_performance_notifications, `PERFORMANCE` notifications>> * <<_hint_notifications, `HINT` notifications>> @@ -3369,7 +3369,7 @@ Use `DATABASE *` without the parameter to revoke the privilege on all databases. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Security.AuthProviderNotDefined |Title a|The auth provider is not defined. @@ -3485,7 +3485,7 @@ If it is correct, make sure to add it as a known auth provider in one or both of .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code m|Neo.ClientNotification.Security.ExternalAuthNotEnabled |Title a|External auth for user is not enabled. diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 42c89a7c..7efb88cf 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -7,6 +7,7 @@ After a successful query execution, the Neo4j server sends notifications to prov The driver receives these notifications and sends them to the client, which displays them to the user. From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API. +The Notification API is deprecated since Neo4j 5.26. The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. This page describes both the GQL-status object and the Neo4j Notification frameworks, how they are structured, the objects they provide for notifications, and how to interpret them. @@ -148,18 +149,19 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their |=== -[[neo4j-notification-object]] -== Neo4j notification object +[role=label--deprecated-5.26] +[[legacy-notification-object]] +== Legacy notification object -The Neo4j notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. +The Neo4j legacy notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. Depending on the application, some of the fields from the notification object might not be visible. -The notification object consists of the following fields: +The legacy notification object consists of the following fields: -.Neo4j notification object +.Neo4j legacy notification object [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. |Title a|The title of the Neo4j status code. @@ -244,6 +246,7 @@ The following notification groups exist in Neo4j, ordered by severity: | |=== +[role=label--deprecated-5.26] [[notification-internals]] == Notification internals @@ -252,7 +255,7 @@ During the handshake process, they agree on using the newest possible Bolt proto For more information on the Bolt versions supported by different server versions, see the link:https://neo4j.com/docs/bolt/current/bolt-compatibility[Bolt Protocol documentation]. On the server side, notifications are part of the Result Core API. -A method called `getNotifications()` returns a list of server-side notification objects. +A method called `getNotifications()`, which is deprecated since 5.26, returns a list of server-side notification objects. These notifications are then sent to the driver as success Bolt message metadata. On the driver side, notifications are part of the ResultSummary API, which has a method called `notifications()` that returns a list of driver-side Notification objects. The result of the `getCode()` or `code()` methods is known as the Neo4j status code. @@ -261,6 +264,7 @@ For more information, see < Date: Tue, 5 Nov 2024 12:16:44 +0000 Subject: [PATCH 03/29] Add more information to the gql frameworks --- modules/ROOT/pages/draft.adoc | 32 ---- modules/ROOT/pages/errors/index.adoc | 164 +++++++++++--------- modules/ROOT/pages/index.adoc | 4 +- modules/ROOT/pages/notifications/index.adoc | 5 +- 4 files changed, 96 insertions(+), 109 deletions(-) delete mode 100644 modules/ROOT/pages/draft.adoc diff --git a/modules/ROOT/pages/draft.adoc b/modules/ROOT/pages/draft.adoc deleted file mode 100644 index f561c18e..00000000 --- a/modules/ROOT/pages/draft.adoc +++ /dev/null @@ -1,32 +0,0 @@ -In GQL, when the execution of a GQL-request fails, the execution outcome (in this case failed outcome) has no results but only a primary GQL-status object describing the exception condition (i.e., the error) that caused the failure and possibly a list of other additional GQL-status objects describing other conditions related to the same GQL-request. - -A GQL-status object comprises: -A mandatory GQLSTATUS code, which is a 5 character string identifying a condition (the first 2 characters identify the GQLSTATUS class code and the 3 other characters identify the GQLSTATUS subclass code) -A mandatory status description, which is a user-facing message describing the GQLSTATUS -An optional record with diagnostic information (such as the code of the operation executed, the current working directory, etc.) -An optional nested GQL-status object for providing additional diagnostic information, such as a cause. -In GQL, it is up to implementations to make several conditions available when a GQL-request is executed. However, if multiple conditions are made available they should be returned in separate GQL-status objects. In this case, there should be a primary GQL-status object and a list of additional GQL-status objects. GQL prescribes the below precedence rules to determine the primary GQL-status object: -Every exception condition for transaction rollback has precedence over every other exception condition. -Every exception condition has precedence over every completion condition. -Note that GQL exception conditions are equivalent to Neo4j errors, and GQL completion conditions include Cypher notifications whose severity level is either warning or information (except those related to performance or variable shadowing, which are equivalent to GQL additional informational messages that can theoretically accompany both completion and exception condition). GQL completion conditions go beyond Cypher notifications. They include no data and successful completion. - - - - in Cypher, if the execution of a request fails, a single GQL-status object describing a specific error is returned, i.e., the primary GQL-status object, which is also GQL-compliant. This is different from the success case, where multiple Cypher notifications can be returned, hence multiple GQL-status objects describing completion conditions and informational conditions. - -Currently, a Neo4j error code can span several Neo4j exceptions and each exception can have several error messages. Each exception can be also linked to several Neo4j error codes. Some codes have no linked exceptions at all (See examples depicted in the table below). Hence, there is a many-to-many relationship between current error codes and exceptions. This is why many of the clients rely on the error message to identify a specific error. - -The ultimate goal is to have a 1-1 mapping between a GQLSTATUS code and a specific error message so as to let the client rely on one unique and standardized code. The next section describes how to assign a single and unique GQLSTATUS code for each error to achieve this goal. - -If a Neo4j error matches a standard-defined condition and subcondition, then the standard-defined GQLSTATUS code should be used for that error. For instance, (Neo.ClientError.Statement.ArithmeticError, ArithmeticException, “/by zero”) matches the “data exception” condition and “division by zero” subcondition in GQL (i.e., 22012 GQLSTATUS code). - -error: data exception - string data, right truncation - - - -Processing of GQL-requests can cause various conditions to be raised. Each such condition is identified by a unique code called GQLSTATUS, which is a character string that always includes a class code that specifies the principle category to which the condition belongs. It may also include a subclass code that specifies additional information about the reason for raising the condition. The exact format of GQLSTATUS codes is specified in Subclause 23.1, “GQLSTATUS”. -For example, the GQLSTATUS '22003' identifies the exception condition “data exception — numeric value out of range”. -The GQLSTATUS codes assigned by this document to conditions are stable and can be depended on to remain constant. -There are two types of conditions: -— completion conditions. -— exception conditions. diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index 597f5971..3d26f599 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -2,29 +2,27 @@ [[neo4j-errors]] = Server errors -A server error is returned by the Neo4j DBMS to indicate that the outcome of a Cypher query or command execution is not successful. +The Neo4j DBMS returns a server error to indicate that the outcome of a Cypher query or command execution is unsuccessful. The driver receives these errors and sends them to the client, which displays them to the user. -Starting from version 5.25, Neo4j has a new GqlStatusObject API in addition to the existing HasStatus API. -The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. +Starting from version 5.25, the Neo4j error codes have an additional GQL-status object that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. -This page describes both the Neo4j error and the GQL-status object frameworks, how they are structured, the objects they provide for errors, and how to interpret them. -//It also explains the server error grouping and filtering, the error internals, and the server-driver compatibility for both the HasStatus and GqlStatusObject APIs. +This page describes the GQL-status object and the Neo4j error frameworks, their structure, the objects they provide for errors, and how to interpret them. +It also explains the error internals and the server-driver compatibility for both the GQLSTATUS and legacy errors. - -[role=label--version-5.23] +[role=label--version-5.25] [[gqlstatus-error-object]] == GQL-status error object In the GQL-status object framework, errors are an implementation-defined subset of the GQL-status objects that cover exceptions. In GQL, the execution of a query from user to server always has an outcome, called the _execution outcome_. -The execution outcome is a list of GQL-status objects, ordered by the following precedence, where the first object in the list is the primary GQL-status object: +The execution outcome is a list of GQL-status objects ordered by the following precedence rules: -. Every exception condition for transaction rollback has precedence over every other exception condition. -. Every exception condition has precedence over every completion condition. +. Every exception that results in a transaction rollback takes precedence over other exceptions. +. Every exception takes precedence over any completion condition. -The GQL-status object also includes the Neo4j-specific information, such as the severity level and the classification of the error. +The GQL-status object also includes the Neo4j-specific information, such as the severity level and the error classification. Each GQL-status object consists of the following fields: @@ -47,75 +45,57 @@ Additional helper methods are exposed for some useful fields. ! `OPERATION_CODE` ! The operation code that the error is related to. Always defaults to `0`. ! `CURRENT_SCHEMA` ! The current schema that the error is related to. Always defaults to `/`. ! `_severity` a! The Neo4j severity level of the error, which is always `ERROR`. -!`_classification` ! The Neo4j category of the error, which can be `CLIENT_ERROR`, `TRANSIENT_ERROR`, or `DATABASE_ERROR`. +!`_classification` ! The Neo4j error classification, which can be `CLIENT_ERROR`, `TRANSIENT_ERROR`, or `DATABASE_ERROR`. ! `_position` ! The position, given by row and column, where the error is relevant in the query text. //! `_status_parameters`! A map that contains all variable parts of the status description. !=== |=== -A GQL-status error object can also contain an optional nested GQL-status object for providing additional diagnostic information, such as a cause, which is a GQL-status object wrapped in another GQL-status object. +A GQL-status error object can also contain an optional wrapped GQL-status object to provide additional diagnostic information, such as a cause. [[gqlstatus-neo4j-defined-codes]] == Classes of GQLSTATUS error codes -The Neo4j-defined GQLSTATUS codes are divided into classes and subclasses, where the class code is a 2-character string (one of `00`, `01`, or `03`) and the subclass code is a 3-character string. -The class code indicates the general condition of the status (such as successful completion, warning, or information), and the subclass code provides more detailed information about the condition, such as classification and messages. +The Neo4j GQLSTATUS codes are divided into classes and subclasses. +The class code is a 2-character string that indicates the general condition of the status, such as connection exception, data exception, etc. +The subclass code is a 3-character string that provides more detailed information about the condition. +The Neo4j-define subclasses start with N, followed by a 2-digit number. -The following table lists the Neo4j-defined groups of GQLSTATUS codes and their meanings: +The following table lists the GQLSTATUS classes and their meanings: -.GQLSTATUS groups of codes as defined by Neo4j +.GQLSTATUS code classes [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== -|GQLSTATUS code +|Class |*Description* -| 01N0[y] -| Deprecation warnings - -| 01N3[y] -| Hint warnings - -| 01N4[y] -| Unsupported warnings - -| 01N5[y] -| Unrecognized warnings - -| 01N6[y] -| Generic warnings - -| 01N7[y] -| Security warnings - -| 03N9[y] -| Performance information - -| 03N6[y] -| Generic information - -| 00N5[y] -| Unrecognized information under successful completion - -| 00N6[y] -| Generic information under successful completion - -| 00N7[y] -| Security information under successful completion - -| 00N8[y] -| Topology information under successful completion - +| 08 +| connection exception +| 22 +| data exception +| 25 +| invalid transaction state +| 40 +| transaction rollback +| 42 +| syntax error or access rule violation +| 50 +| general processing exception +| 51 +| system configuration or operation exception +| 52 +| procedure exception |=== -[[neo4j-error-object]] -== Neo4j error object +[[legacy-error-object]] +== Legacy error object -The Neo4j error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. +The Neo4j legacy error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. Depending on the application, some of the fields from the error object might not be visible. The error object consists of the following fields: -.Neo4j error object +.Neo4j legacy error object [cols="<1s,<4"] |=== |Neo4j code @@ -133,31 +113,38 @@ Available categories are `CLIENT_ERROR`, `TRANSIENT_ERROR`, and `DATABASE_ERROR` a|The position, given by row and column, where the error is relevant in the query text. |=== +For more information, see the xref:errors/all-errors.adoc[List of legacy server error codes]. + [[error-grouping-and-filtering]] == Server error classification -The fact that a Neo4j status code is returned by the server does not always mean there is a fatal error. -Neo4j status codes can also indicate transient problems that may go away if you retry the request. -The status code classification determines the effect on the transaction. +The fact that an error is returned by the server does not always mean that it is a fatal error. +Status codes can also indicate transient problems that may go away if you retry the request. +The server error classification determines the effect on the transaction. -.Neo4j status code types +.Server error classification [options="header", cols="<1m,<2,<1"] |=== -| Type +| Classification | Description | Effect on the transaction | xref:errors/all-errors.adoc#_client_errors[ClientError] -| The client sent a bad request - changing the request might yield a successful outcome. +| These errors are caused by the client and are usually related to the request itself. +Changing the request might yield a successful outcome. +Legacy client errors have the prefix `Neo.ClientError`. | Rollback | xref:errors/all-errors#_transient_errors[TransientError] -| The database cannot service the request right now, retrying later might yield a successful outcome. +| These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. +The error can be temporary, therefore retrying later might yield a successful outcome. +Legacy transient errors have the prefix Neo.`TransientError`. | Rollback | xref:errors/all-errors#_database_error[DatabaseError] -| The database failed to service the request. +| These errors are caused by the database and are usually related to the database state and mean that the database failed to service the request. +Legacy database errors have the prefix `Neo.DatabaseError`. | Rollback |=== @@ -165,16 +152,49 @@ The status code classification determines the effect on the transaction. [[error-internals]] == Error internals -The server and driver communicate with each other through the Bolt protocol. -During the handshake process, they agree on using the newest possible Bolt protocol version that both the server and the driver support. -For more information on the Bolt versions supported by different server versions, see the link:https://neo4j.com/docs/bolt/current/bolt-compatibility[Bolt Protocol documentation]. - Neo4j supports server errors in the form of Java exceptions. Most of these implement the `HasStatus` interface, which means they have a Neo4j status code in addition to the exception message. On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the Neo4j status code. -These exceptions are then sent to the driver as failure Bolt message metadata. + +Starting from 5.25, the exceptions also get new compulsary fields for `gqlStatus` and `statusDescription`, and optional fields for the `diagnosticRecord` and `cause`. +The cause field is a wrapped underlying Neo4j exception, which in turn has its own GQLSTATUS, statusdescription, diagnostic record and message. + +The `getMessage()` method is kept as Java exceptions inherently have this method. +And a new classification field is added to cover the division of client errors, transient errors and database errors, which today is part of the Neo4j status code. +All of these fields construct the GQLSTATUS object, which is sent to the driver as part of the Failure Bolt message. +Exactly how this looks, depends on the combination of driver and server versions. +See <> for more information. + +On the driver side, the Neo4jException is extended with the corresponding methods as on the server side. +The driver receives the failure message and extracts the status code and the error message. +Then, it constructs an error object with the status code, error message, and other relevant information, and sends it to the client. + +// Starting from 2025.01, the diagnostic record also contains a `_status_parameters` field, which represens a map that contains all variable parts of the status description, such as labels, database names, Cypher clauses, etc. +// This field is used to provide more detailed information about the error. + +== Query logging + +Since the query log is server-side and DBMS wide, multiple clients connected to the same DBMS write to the same query log. +As the clients can have separate driver versions, they may have different error framework formats. + +In Neo4j 5.25, the default JSON template for the query log is updated to include `errorInfo` entry. +This entry contains `GQLSTATUS`, `statusDescription`, `classification`, `position` (if applicable), and `cause` (if applicable) with the same entries. +//The `failureReason` entry is deprecated from 5.26. + +[NOTE] +==== +The default GQLSTATUS code 50N42 is returned when an exception does not have a GQL object. Starting from Neo4j 5.25, GQL objects are added to exceptions; therefore, you can expect many 50N42 codes. However, it’s important not to rely on this default code, as future Neo4j versions might change it by adding an appropriate GQL object to the exception. Additionally, GQL codes for external procedures are not yet stable. +==== + +// Starting from Neo4j 2025.01, a new JSON template is available for the query log, which is the default set in server_log.xml. +// It contains the `errorInfo` entry, but not the `failureReason` entry, which is switched off by default. [[server-driver-compatibility]] -== Server-driver version compatibility \ No newline at end of file +== Server-driver version compatibility + +The server and driver communicate with each other through the Bolt protocol. +During the handshake process, they agree on using the newest possible Bolt protocol version that both the server and the driver support. +For more information on the Bolt versions supported by different server versions, see the link:https://neo4j.com/docs/bolt/current/bolt-compatibility[Bolt Protocol documentation]. + + diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index b0081f36..f2c11c7f 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -13,10 +13,10 @@ The Neo4j 5 Status Codes manual includes all status codes that a Neo4j server ma Starting from 5.23 for notifications and 5.25 for errors, the Neo4j DBMS supports the GQL standard. + GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases. -Cypher®, Neo4j’s query language, supports most mandatory and a substantial portion of the optional GQL features (as defined by the ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard). +Cypher®, Neo4j’s query language, supports most mandatory and a substantial portion of the optional GQL features (as defined by the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]). For more information, see link:https:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance]. -As part of this GQL compliance, Cypher now also include status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. +As part of this GQL compliance, Cypher now also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. For more information on GQL status code framewoks for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. This manual details all status codes that a Neo4j DBMS may return, including both GQL-compliant and legacy status codes. diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 7efb88cf..dc76e45f 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -6,9 +6,8 @@ After a successful query execution, the Neo4j server sends notifications to provide advice on how to improve the query's quality or give additional information about the query execution. The driver receives these notifications and sends them to the client, which displays them to the user. -From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API. -The Notification API is deprecated since Neo4j 5.26. -The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. +From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API (deprecated since 5.26). +The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. This page describes both the GQL-status object and the Neo4j Notification frameworks, how they are structured, the objects they provide for notifications, and how to interpret them. It also explains the server notification grouping and filtering, the notification internals, and the server-driver compatibility for both the Notification and GqlStatusObject APIs. From 43146bdde5b8f48e1d0cdd239748caef66fc87b2 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 16:54:15 +0000 Subject: [PATCH 04/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 61f372d2..aecb08b9 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -10,7 +10,7 @@ Errors are grouped based on the type of the error code: Client errors:: These errors are caused by the client and are usually related to the request itself. -Client errors have the prefix `Neo.ClientError`. +The Neo4j status code for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. From 84b493d0828e386a6981369aad45cb5a463f6da8 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 16:54:22 +0000 Subject: [PATCH 05/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index aecb08b9..11e6d222 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -6,7 +6,7 @@ Error codes are Neo4j status codes returned by the server when the execution of a query fails. They always have the severity level `ERROR`. -Errors are grouped based on the type of the error code: +Errors are grouped based on the type of the Neo4j status code: Client errors:: These errors are caused by the client and are usually related to the request itself. From 60a20fc7b97af20bf674e499489fcb605b14b413 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 16:57:31 +0000 Subject: [PATCH 06/29] Update modules/ROOT/pages/errors/all-errors.adoc --- modules/ROOT/pages/errors/all-errors.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 11e6d222..55f509ef 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -4,7 +4,10 @@ [[neo4j-errors]] = List of legacy server error codes -Error codes are Neo4j status codes returned by the server when the execution of a query fails. +This page lists the legacy server error codes, also known as Neo4j status codes. +These will be replaced by xref:errors/gql-errors.adoc[GQLSTATUS server error codes]. + +Neo4j status codes are returned by the server when the execution of a query fails. They always have the severity level `ERROR`. Errors are grouped based on the type of the Neo4j status code: From 724455fc043c7e5cdc7b21ad9c99fa9c6ff55bcf Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 16:59:10 +0000 Subject: [PATCH 07/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 55f509ef..38dc8d63 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -17,7 +17,7 @@ The Neo4j status code for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. -The error can be temporary and could therefore succeed if retrying the request. +The error can be temporary, and the request could succeed if retried. Transient errors have the prefix Neo.`TransientError`. Database errors:: From fffb8ee5211933237e1bf7ecf4dbd8f4d7054791 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 16:59:31 +0000 Subject: [PATCH 08/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 38dc8d63..f5b146dc 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -18,7 +18,7 @@ The Neo4j status code for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. The error can be temporary, and the request could succeed if retried. -Transient errors have the prefix Neo.`TransientError`. +The Neo4j status code for transient errors have the prefix Neo.`TransientError`. Database errors:: These errors are caused by the database and are usually related to the database state. From ccdd1c31432042699b3e3bd69e9ade62919cb923 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 16:59:38 +0000 Subject: [PATCH 09/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index f5b146dc..8bef24c3 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -22,7 +22,7 @@ The Neo4j status code for transient errors have the prefix Neo.`TransientError`. Database errors:: These errors are caused by the database and are usually related to the database state. -Database errors have the prefix `Neo.DatabaseError`. +The Neo4j status code for database errors have the prefix `Neo.DatabaseError`. This page contains lists of all Neo4j errors, grouped by type. From 82140622657d7f059062cb9589473795cc9e8458 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 20 Nov 2024 17:01:16 +0000 Subject: [PATCH 10/29] Update modules/ROOT/pages/index.adoc --- modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index f2c11c7f..efa3532b 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -17,7 +17,7 @@ Cypher®, Neo4j’s query language, supports most mandatory and a substantial po For more information, see link:https:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance]. As part of this GQL compliance, Cypher now also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. -For more information on GQL status code framewoks for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. +For more information on the GQL-status object framework for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. This manual details all status codes that a Neo4j DBMS may return, including both GQL-compliant and legacy status codes. From 07dab7d8dd2ff1df94170b0653f713aa673eb0b1 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 25 Nov 2024 13:34:27 +0100 Subject: [PATCH 11/29] apply some feedback from reviews --- modules/ROOT/pages/errors/all-errors.adoc | 14 ++++----- modules/ROOT/pages/errors/gql-errors.adoc | 2 +- modules/ROOT/pages/errors/index.adoc | 35 ++++++++++++--------- modules/ROOT/pages/index.adoc | 2 +- modules/ROOT/pages/notifications/index.adoc | 15 ++++++--- 5 files changed, 39 insertions(+), 29 deletions(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 8bef24c3..5e7c71e6 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -7,22 +7,22 @@ This page lists the legacy server error codes, also known as Neo4j status codes. These will be replaced by xref:errors/gql-errors.adoc[GQLSTATUS server error codes]. -Neo4j status codes are returned by the server when the execution of a query fails. +Error codes are returned by the server when the execution of a query fails. They always have the severity level `ERROR`. Errors are grouped based on the type of the Neo4j status code: Client errors:: These errors are caused by the client and are usually related to the request itself. -The Neo4j status code for client errors have the prefix `Neo.ClientError`. +The Neo4j status codes for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. The error can be temporary, and the request could succeed if retried. -The Neo4j status code for transient errors have the prefix Neo.`TransientError`. +The Neo4j status codes for transient errors have the prefix Neo.`TransientError`. Database errors:: These errors are caused by the database and are usually related to the database state. -The Neo4j status code for database errors have the prefix `Neo.DatabaseError`. +The Neo4j status codes for database errors have the prefix `Neo.DatabaseError`. This page contains lists of all Neo4j errors, grouped by type. @@ -33,7 +33,7 @@ This is a complete list of all client errors Neo4j may return, and what they mea [options="header", cols="<1m,<1"] |=== -| Neo4j status code +| Neo4j legacy code | Description | Neo.ClientError.ChangeDataCapture.InvalidIdentifier @@ -299,7 +299,7 @@ This is a complete list of all transient errors Neo4j may return, and what they [options="header", cols="<1m,<1"] |=== -| Neo4j status code +| Neo4j legacy code | Description | Neo.TransientError.ChangeDataCapture.FutureIdentifier @@ -406,7 +406,7 @@ This is a complete list of all database errors Neo4j may return, and what they m [options="header", cols="<1m,<1"] |=== -| Neo4j status code +| Neo4j legacy code | Description | Neo.DatabaseError.ChangeDataCapture.Disabled diff --git a/modules/ROOT/pages/errors/gql-errors.adoc b/modules/ROOT/pages/errors/gql-errors.adoc index 63c4716b..77a85ef4 100644 --- a/modules/ROOT/pages/errors/gql-errors.adoc +++ b/modules/ROOT/pages/errors/gql-errors.adoc @@ -9,7 +9,7 @@ All errors in Neo4j have severity level `ERROR`. == Connection exceptions -Connection exceptions occur when the client is unable to connect to the server for various reasons such as network issues, server-side routing being disabled, or the database being unavailable, etc. +Connection exceptions occur when the client (e.g. Browser/Bloom/Cypher Shell) is unable to connect to the server for various reasons such as network issues, server-side routing being disabled, or the database being unavailable, etc. === 08000 diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index 3d26f599..e0fb0f0d 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -3,9 +3,8 @@ = Server errors The Neo4j DBMS returns a server error to indicate that the outcome of a Cypher query or command execution is unsuccessful. -The driver receives these errors and sends them to the client, which displays them to the user. -Starting from version 5.25, the Neo4j error codes have an additional GQL-status object that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. +Starting from version 5.25, the Neo4j error codes have an additional GQL-status object along with the Neo4j exception that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. This page describes the GQL-status object and the Neo4j error frameworks, their structure, the objects they provide for errors, and how to interpret them. It also explains the error internals and the server-driver compatibility for both the GQLSTATUS and legacy errors. @@ -30,10 +29,11 @@ Each GQL-status object consists of the following fields: [cols="<1s,<4"] |=== |GQLSTATUS code -a| A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code. +a| A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code, which identifies the condition of the error. |StatusDescription -a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and a description. +a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and an optional additional text about the condition. The condition and subcondition are textual representations of the class and subclass codes, respectively. +The subcondition for the subclass 000 is empty. | DiagnosticRecord a| Extra information about the status, given as key-value pairs, both on the server and driver side. To retrieve the full diagnostic record, you can use the `diagnosticRecord()` method on both the server and driver sides. @@ -44,14 +44,15 @@ Additional helper methods are exposed for some useful fields. ! `OPERATION` ! The operation that the error is related to. Always defaults to empty. ! `OPERATION_CODE` ! The operation code that the error is related to. Always defaults to `0`. ! `CURRENT_SCHEMA` ! The current schema that the error is related to. Always defaults to `/`. -! `_severity` a! The Neo4j severity level of the error, which is always `ERROR`. +//! `_severity` a! The Neo4j severity level of the error, which is always `ERROR`. !`_classification` ! The Neo4j error classification, which can be `CLIENT_ERROR`, `TRANSIENT_ERROR`, or `DATABASE_ERROR`. -! `_position` ! The position, given by row and column, where the error is relevant in the query text. +! `_position` ! (Optional) The position, given by offset, line and column, where the error is relevant in the query text. //! `_status_parameters`! A map that contains all variable parts of the status description. !=== |=== -A GQL-status error object can also contain an optional wrapped GQL-status object to provide additional diagnostic information, such as a cause. +A GQL-status error object can also contain an optional wrapped GQL-status object. +This wrapped object is referred to as a `cause` and used to provide additional, more specific diagnostic information. [[gqlstatus-neo4j-defined-codes]] == Classes of GQLSTATUS error codes @@ -59,7 +60,7 @@ A GQL-status error object can also contain an optional wrapped GQL-status object The Neo4j GQLSTATUS codes are divided into classes and subclasses. The class code is a 2-character string that indicates the general condition of the status, such as connection exception, data exception, etc. The subclass code is a 3-character string that provides more detailed information about the condition. -The Neo4j-define subclasses start with N, followed by a 2-digit number. +The Neo4j-define subclasses start with N, followed by a 2-digit number, while the ones that do not start with N are standard-defined subclasses. The following table lists the GQLSTATUS classes and their meanings: @@ -67,7 +68,7 @@ The following table lists the GQLSTATUS classes and their meanings: [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== |Class -|*Description* +|*Condition* | 08 | connection exception @@ -98,7 +99,7 @@ The error object consists of the following fields: .Neo4j legacy error object [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j legacy code a|The Neo4j status code in the form of `Neo.[Type].[SubType].[Name]`. |Description a|The description of the specific error. @@ -110,7 +111,7 @@ a|`ERROR` a|The category of the error. Available categories are `CLIENT_ERROR`, `TRANSIENT_ERROR`, and `DATABASE_ERROR`. |Position -a|The position, given by row and column, where the error is relevant in the query text. +a|(Optional) The position, given by offset, line and column, where the error is relevant in the query text. |=== For more information, see the xref:errors/all-errors.adoc[List of legacy server error codes]. @@ -157,7 +158,7 @@ Most of these implement the `HasStatus` interface, which means they have a Neo4j On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the Neo4j status code. -Starting from 5.25, the exceptions also get new compulsary fields for `gqlStatus` and `statusDescription`, and optional fields for the `diagnosticRecord` and `cause`. +Starting from 5.25, the exceptions also get new compulsary fields for `gqlStatus`, `statusDescription`, `diagnosticRecord`, and an optional field for `cause`. The cause field is a wrapped underlying Neo4j exception, which in turn has its own GQLSTATUS, statusdescription, diagnostic record and message. + The `getMessage()` method is kept as Java exceptions inherently have this method. And a new classification field is added to cover the division of client errors, transient errors and database errors, which today is part of the Neo4j status code. @@ -166,7 +167,7 @@ Exactly how this looks, depends on the combination of driver and server versions See <> for more information. On the driver side, the Neo4jException is extended with the corresponding methods as on the server side. -The driver receives the failure message and extracts the status code and the error message. +The driver receives the Failure Bolt message and extracts the status code and the error message. Then, it constructs an error object with the status code, error message, and other relevant information, and sends it to the client. // Starting from 2025.01, the diagnostic record also contains a `_status_parameters` field, which represens a map that contains all variable parts of the status description, such as labels, database names, Cypher clauses, etc. @@ -179,11 +180,15 @@ As the clients can have separate driver versions, they may have different error In Neo4j 5.25, the default JSON template for the query log is updated to include `errorInfo` entry. This entry contains `GQLSTATUS`, `statusDescription`, `classification`, `position` (if applicable), and `cause` (if applicable) with the same entries. -//The `failureReason` entry is deprecated from 5.26. +The `failureReason` entry is deprecated from 5.26. [NOTE] ==== -The default GQLSTATUS code 50N42 is returned when an exception does not have a GQL object. Starting from Neo4j 5.25, GQL objects are added to exceptions; therefore, you can expect many 50N42 codes. However, it’s important not to rely on this default code, as future Neo4j versions might change it by adding an appropriate GQL object to the exception. Additionally, GQL codes for external procedures are not yet stable. +The default GQLSTATUS code 50N42 is returned when an exception does not have a GQL-status object. +Starting from Neo4j 5.25, we started adding GQL objects to exceptions. +Therefore, you can expect many 50N42 codes during this transition period. +However, it is important not to rely on this default code, as future Neo4j versions might change it by adding an appropriate GQL object to the exception. +Additionally, GQL codes for external procedures are not yet stable. ==== // Starting from Neo4j 2025.01, a new JSON template is available for the query log, which is the default set in server_log.xml. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index efa3532b..7ab46f7c 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -19,7 +19,7 @@ For more information, see link:https:https://neo4j.com/docs/cypher-manual/curren As part of this GQL compliance, Cypher now also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. For more information on the GQL-status object framework for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. -This manual details all status codes that a Neo4j DBMS may return, including both GQL-compliant and legacy status codes. +This manual details all status codes that a Neo4j DBMS may return, including both GQL-compliant and legacy Neo4j status codes. ifndef::backend-pdf[] License: link:{common-license-page-uri}[Creative Commons 4.0] diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index dc76e45f..e3aabf47 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -4,7 +4,7 @@ = Server notifications After a successful query execution, the Neo4j server sends notifications to provide advice on how to improve the query's quality or give additional information about the query execution. -The driver receives these notifications and sends them to the client, which displays them to the user. +The driver receives these notifications and sends them to the client (e.g. Browser/Bloom/Cypher Shell), which displays them to the user. From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API (deprecated since 5.26). The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. @@ -34,14 +34,19 @@ The GQL-status object also includes the Neo4j-specific information, such as the For more information about notification grouping and filtering, see <>. Each GQL-status object consists of the following fields: - +— A GQLSTATUS, which is a character string identifying a condition as defined in Subclause 23.1, +“GQLSTATUS”. +— A status description, which is a character string describing the GQLSTATUS. +— A record with diagnostic information as defined in Subclause 23.2, “Diagnostic records”. +— An optional nested GQL-status object for providing additional diagnostic information, such as a +cause. .GQLSTATUS notification object [cols="<1s,<4"] |=== |GQLSTATUS code -a| A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code. +a| A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code, which identifies the condition of the notification. |StatusDescription -a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and a description. +a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and an optional additional text about the condition. The condition and subcondition are textual representations of the class and subclass codes, respectively. | DiagnosticRecord a| Extra information about the status, given as key-value pairs, both on the server and driver side. @@ -257,7 +262,7 @@ On the server side, notifications are part of the Result Core API. A method called `getNotifications()`, which is deprecated since 5.26, returns a list of server-side notification objects. These notifications are then sent to the driver as success Bolt message metadata. On the driver side, notifications are part of the ResultSummary API, which has a method called `notifications()` that returns a list of driver-side Notification objects. -The result of the `getCode()` or `code()` methods is known as the Neo4j status code. +The result of the `getCode()` or `code()` methods is known as the legacy Neo4j status code. Driver-side notification configuration filters notifications by severity and/or category at both the driver and session levels. For more information, see <>. From 6e7b23105a142a949fe42d42cb2b28581f181ce3 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 27 Nov 2024 10:52:26 +0000 Subject: [PATCH 12/29] remove legacy and further updates --- README.adoc | 2 +- antora.yml | 2 +- modules/ROOT/pages/changelogs.adoc | 12 ++ modules/ROOT/pages/errors/all-errors.adoc | 17 +- modules/ROOT/pages/errors/index.adoc | 56 ++--- modules/ROOT/pages/index.adoc | 8 +- .../notifications/all-notifications.adoc | 196 +++++++++--------- modules/ROOT/pages/notifications/index.adoc | 20 +- 8 files changed, 164 insertions(+), 149 deletions(-) diff --git a/README.adoc b/README.adoc index 8a1a1fd5..e4c11f22 100644 --- a/README.adoc +++ b/README.adoc @@ -2,7 +2,7 @@ = docs-status-codes -This repository contains the AsciiDoc and other sources to build the link:{docs-uri}/status-codes[Neo4j Status Codes]. +This repository contains the AsciiDoc and other sources to build the link:{docs-uri}/status-codes[Status Codes for Errors & Notifications]. [[local-build]] == Installation diff --git a/antora.yml b/antora.yml index adc29f5f..f2cce874 100644 --- a/antora.yml +++ b/antora.yml @@ -1,5 +1,5 @@ name: status-codes -title: Status Codes +title: Status Codes for Errors & Notifications version: '5' start_page: ROOT:index.adoc nav: diff --git a/modules/ROOT/pages/changelogs.adoc b/modules/ROOT/pages/changelogs.adoc index dc20db84..03175695 100644 --- a/modules/ROOT/pages/changelogs.adoc +++ b/modules/ROOT/pages/changelogs.adoc @@ -1,6 +1,18 @@ :description: This page lists all changes to status codes per Neo4j version. = Changes to status codes per Neo4j version +== Neo4j 5.26 + +**Changed:** +Using differently ordered return items in a `UNION [ALL]` clause has been undeprecated following cost-benefit analysis and valuable user feedback. + +== Neo4j 5.25 + +**New:** + +Starting from 5.25, the query log includes the GQL error information under the JSON object `errorInfo`. +For more information, see link:https://neo4j.com/docs/operations-manual/current/monitoring/logging/#gql-error-information[Operations Manual -> GQL error information]. + == Neo4j 5.24 **New:** diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 5e7c71e6..8963dcf6 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -1,19 +1,18 @@ -:description: The legacy error codes for Neo4j 5. +:description: The error codes for Neo4j 5. [[neo4j-errors]] -= List of legacy server error codes += List of Neo4j codes -This page lists the legacy server error codes, also known as Neo4j status codes. -These will be replaced by xref:errors/gql-errors.adoc[GQLSTATUS server error codes]. +This page lists the current Neo4j error codes, which will be replaced by xref:errors/gql-errors.adoc[GQLSTATUS error codes] in the future. Error codes are returned by the server when the execution of a query fails. They always have the severity level `ERROR`. Errors are grouped based on the type of the Neo4j status code: Client errors:: -These errors are caused by the client and are usually related to the request itself. -The Neo4j status codes for client errors have the prefix `Neo.ClientError`. +These errors are caused by the client (user input or user application) and are usually related to the request itself. +The Neo4j codes for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. @@ -33,7 +32,7 @@ This is a complete list of all client errors Neo4j may return, and what they mea [options="header", cols="<1m,<1"] |=== -| Neo4j legacy code +| Neo4j code | Description | Neo.ClientError.ChangeDataCapture.InvalidIdentifier @@ -299,7 +298,7 @@ This is a complete list of all transient errors Neo4j may return, and what they [options="header", cols="<1m,<1"] |=== -| Neo4j legacy code +| Neo4j code | Description | Neo.TransientError.ChangeDataCapture.FutureIdentifier @@ -406,7 +405,7 @@ This is a complete list of all database errors Neo4j may return, and what they m [options="header", cols="<1m,<1"] |=== -| Neo4j legacy code +| Neo4j code | Description | Neo.DatabaseError.ChangeDataCapture.Disabled diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index e0fb0f0d..ae9cc7b7 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -6,8 +6,14 @@ The Neo4j DBMS returns a server error to indicate that the outcome of a Cypher q Starting from version 5.25, the Neo4j error codes have an additional GQL-status object along with the Neo4j exception that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. +[NOTE] +==== +This additional GQL-status object is currently displayed only in the query log. +For more information, see link:https://neo4j.com/docs/operations-manual/current/monitoring/logging/#gql-error-information[Operations Manual -> GQL error information]. +==== + This page describes the GQL-status object and the Neo4j error frameworks, their structure, the objects they provide for errors, and how to interpret them. -It also explains the error internals and the server-driver compatibility for both the GQLSTATUS and legacy errors. +It also explains the error internals and the server-driver compatibility for both the GQLSTATUS and errors. [role=label--version-5.25] [[gqlstatus-error-object]] @@ -57,7 +63,7 @@ This wrapped object is referred to as a `cause` and used to provide additional, [[gqlstatus-neo4j-defined-codes]] == Classes of GQLSTATUS error codes -The Neo4j GQLSTATUS codes are divided into classes and subclasses. +The GQLSTATUS codes are divided into classes and subclasses. The class code is a 2-character string that indicates the general condition of the status, such as connection exception, data exception, etc. The subclass code is a 3-character string that provides more detailed information about the condition. The Neo4j-define subclasses start with N, followed by a 2-digit number, while the ones that do not start with N are standard-defined subclasses. @@ -88,19 +94,19 @@ The following table lists the GQLSTATUS classes and their meanings: | procedure exception |=== -[[legacy-error-object]] -== Legacy error object +[[-error-object]] +== Neo4j error object -The Neo4j legacy error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. +The Neo4j error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. Depending on the application, some of the fields from the error object might not be visible. The error object consists of the following fields: -.Neo4j legacy error object +.Neo4j error object [cols="<1s,<4"] |=== -|Neo4j legacy code -a|The Neo4j status code in the form of `Neo.[Type].[SubType].[Name]`. +|Neo4j code +a|The Neo4j code in the form of `Neo.[Type].[SubType].[Name]`. |Description a|The description of the specific error. |Message @@ -114,38 +120,38 @@ Available categories are `CLIENT_ERROR`, `TRANSIENT_ERROR`, and `DATABASE_ERROR` a|(Optional) The position, given by offset, line and column, where the error is relevant in the query text. |=== -For more information, see the xref:errors/all-errors.adoc[List of legacy server error codes]. +For more information, see the xref:errors/all-errors.adoc[List of Neo4j error codes]. -[[error-grouping-and-filtering]] -== Server error classification +[[error-types]] +== Types of server errors The fact that an error is returned by the server does not always mean that it is a fatal error. Status codes can also indicate transient problems that may go away if you retry the request. -The server error classification determines the effect on the transaction. +The server error group determines the effect on the transaction. -.Server error classification +.Server error types [options="header", cols="<1m,<2,<1"] |=== -| Classification +| Type | Description | Effect on the transaction -| xref:errors/all-errors.adoc#_client_errors[ClientError] -| These errors are caused by the client and are usually related to the request itself. +| ClientError +| These errors are caused by the client (user input or user application) and are usually related to the request itself. Changing the request might yield a successful outcome. -Legacy client errors have the prefix `Neo.ClientError`. + Neo4j codes have the prefix `Neo.ClientError`, while the GQLSTATUS codes have `ErrorClassification` of type `CLIENT_ERROR`. | Rollback -| xref:errors/all-errors#_transient_errors[TransientError] +| TransientError | These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. The error can be temporary, therefore retrying later might yield a successful outcome. -Legacy transient errors have the prefix Neo.`TransientError`. +Neo4j codes have the prefix Neo.`TransientError`, while the GQLSTATUS codes have `ErrorClassification` of type `TRANSIENT_ERROR`. | Rollback -| xref:errors/all-errors#_database_error[DatabaseError] +| DatabaseError | These errors are caused by the database and are usually related to the database state and mean that the database failed to service the request. -Legacy database errors have the prefix `Neo.DatabaseError`. +Neo4j codes have the prefix `Neo.DatabaseError`, while the GQLSTATUS codes have `ErrorClassification` of type `DATABASE_ERROR`. | Rollback |=== @@ -154,14 +160,14 @@ Legacy database errors have the prefix `Neo.DatabaseError`. == Error internals Neo4j supports server errors in the form of Java exceptions. -Most of these implement the `HasStatus` interface, which means they have a Neo4j status code in addition to the exception message. +Most of these implement the `HasStatus` interface, which means they have a status code in addition to the exception message. -On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the Neo4j status code. +On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the status code. Starting from 5.25, the exceptions also get new compulsary fields for `gqlStatus`, `statusDescription`, `diagnosticRecord`, and an optional field for `cause`. -The cause field is a wrapped underlying Neo4j exception, which in turn has its own GQLSTATUS, statusdescription, diagnostic record and message. + +The cause field is a wrapped underlying Neo4j exception, which in turn has its own GQLSTATUS, statusdescription, diagnostic record, and message. + The `getMessage()` method is kept as Java exceptions inherently have this method. -And a new classification field is added to cover the division of client errors, transient errors and database errors, which today is part of the Neo4j status code. +And a new classification field is added to cover the division of client errors, transient errors, and database errors, which today is part of the Neo4j code. All of these fields construct the GQLSTATUS object, which is sent to the driver as part of the Failure Bolt message. Exactly how this looks, depends on the combination of driver and server versions. See <> for more information. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 7ab46f7c..3adbb30a 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,15 +1,15 @@ [[status-codes]] ifdef::backend-pdf[] -= Neo4j 5 Status Codes += Status Codes for Errors and Notifications endif::[] ifndef::backend-pdf[] = Introduction endif::[] -:description: The Neo4j status codes for Neo4j version {neo4j-version}. +:description: Status codes for errors and notifications Neo4j 5 :neo4j-buildnumber: {neo4j-version} -The Neo4j 5 Status Codes manual includes all status codes that a Neo4j server may return to indicate the outcome of a Cypher request. +This manual provides status codes for errors and notifications that a Neo4j server may return to indicate the result of a Cypher request. Starting from 5.23 for notifications and 5.25 for errors, the Neo4j DBMS supports the GQL standard. + GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases. @@ -19,8 +19,6 @@ For more information, see link:https:https://neo4j.com/docs/cypher-manual/curren As part of this GQL compliance, Cypher now also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. For more information on the GQL-status object framework for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. -This manual details all status codes that a Neo4j DBMS may return, including both GQL-compliant and legacy Neo4j status codes. - ifndef::backend-pdf[] License: link:{common-license-page-uri}[Creative Commons 4.0] endif::[] diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 15cab4a3..53879f26 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -3,7 +3,7 @@ [[listOfNnotifications]] = List of all server notification codes -The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and Neo4j legacy codes, along with some scenarios and their possible solutions. +The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and Neo4j codes, along with some scenarios and their possible solutions. * <<_performance_notifications, `PERFORMANCE` notifications>> * <<_hint_notifications, `HINT` notifications>> @@ -29,7 +29,7 @@ This notification is returned when there is a Cartesian product in the plan. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.CartesianProduct |Title a|This query builds a cartesian product between disconnected patterns. @@ -82,7 +82,7 @@ MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -120,7 +120,7 @@ This notification is returned when there is no upper bound specified on the vari .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.UnboundedVariableLengthPattern |Title a|The provided pattern is unbounded, consider adding an upper limit to the number of node hops. @@ -176,7 +176,7 @@ WHERE n <> m RETURN p ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -210,7 +210,7 @@ For more information, see link:https://neo4j.com/docs/cypher-manual/current/exec .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.ExhaustiveShortestPath |Title a|Exhaustive shortest path has been planned for your query that means that shortest path graph algorithm might not be used to find the shortest path. @@ -265,7 +265,7 @@ WHERE ANY(n in nodes(p) WHERE n:Label) RETURN p ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -303,7 +303,7 @@ Adding an index could improve the query speed. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.NoApplicableIndex |Title a|Adding a schema index may speed up this query. @@ -353,7 +353,7 @@ Create an index on the label and property you match. CREATE INDEX FOR (n:Person) ON (n.name) ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -386,7 +386,7 @@ This notification is returned when the execution plan for a query contains the ` .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.EagerOperator |Title a|The execution plan for this query contains the Eager operator, which forces all dependent data to be materialized in main memory before proceeding @@ -442,7 +442,7 @@ CALL { RETURN line ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== `LOAD CSV` together with an Eager operator can take up a lot of memory. @@ -482,7 +482,7 @@ RETURN line .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.DynamicProperty |Title a|Queries using dynamic properties will use neither index seeks nor index scans for those properties @@ -536,7 +536,7 @@ MATCH (n:Person) WHERE n.name IS NOT NULL RETURN n; ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -594,7 +594,7 @@ MATCH ()-[r: KNOWS]->() WHERE r.since IS NOT NULL RETURN r ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -628,7 +628,7 @@ For more information about the specific query, see the stack trace in the _debug .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.CodeGenerationFailed |Title a|The database was unable to generate code for the query. A stacktrace can be found in the _debug.log_. @@ -663,7 +663,7 @@ In this case, the query will return an error. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.JoinHintUnfulfillableWarning |Title a|The database was unable to plan a hinted join. @@ -714,7 +714,7 @@ The `JOIN` hint cannot be applied because its specified variable is before the ` The only option for this query is to either remove the hint or modify the query to allow it to be used. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -748,7 +748,7 @@ The only option for this query is to either remove the hint or modify the query .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Schema.HintedIndexNotFound |Title a|The request (directly or indirectly) referred to an index that does not exist. @@ -794,7 +794,7 @@ Suggestions for improvement:: The hinted index does not exist, make sure the label and property are spelled correctly. If the spelling is correct, either create the index or remove the hint from the query. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -844,7 +844,7 @@ Suggestions for improvement:: The hinted index does not exist, make sure the relationship type and property are spelled correctly. If the spelling is correct, either create the index or remove the hint from the query. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -878,7 +878,7 @@ Unrecognized notifications are returned when the query or command mentions entit .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Database.HomeDatabaseNotFound |Title a|The request referred to a home database that does not exist. @@ -923,7 +923,7 @@ Verify that the spelling is correct or create the database for the command to ta Suggestions for improvement:: Verify that the home database name is not misspelled. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -949,7 +949,7 @@ Verify that the home database name is not misspelled. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.UnknownLabelWarning |Title a|The provided label is not in the database. @@ -994,7 +994,7 @@ Suggestions for improvement:: Verify that the label is not misspelled. If you plan to create nodes with that label in the future, no change is needed. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -1020,7 +1020,7 @@ If you plan to create nodes with that label in the future, then no change is nee .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.UnknownRelationshipTypeWarning |Title a|The provided relationship type is not in the database. @@ -1065,7 +1065,7 @@ Suggestions for improvement:: Verify that the relationship type is not misspelled. If you plan to create relationships of this type in the future, no change is needed. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1091,7 +1091,7 @@ If you plan to create relationships of this type in the future, no change is nee .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.UnknownPropertyKeyWarning |Title a|The provided property key is not in the database @@ -1137,7 +1137,7 @@ Suggestions for improvement:: Verify that the property key is not misspelled. If you plan to create that property key in the future, no change is needed. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1164,7 +1164,7 @@ If you plan to create that property key in the future, no change is needed. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.AggregationSkippedNull |Title a|The query contains an aggregation function that skips null values. @@ -1200,7 +1200,7 @@ Returned GQLSTATUS code:: Returned status description:: warn: null value eliminated in set function. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -1224,7 +1224,7 @@ Unsupported notifications are returned when the query or command is trying to us .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.RuntimeUnsupportedWarning |Title a|This query is not supported by the chosen runtime. @@ -1273,7 +1273,7 @@ Use a different runtime or remove the runtime option to run the query with the d SHOW INDEXES YIELD * ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -1310,7 +1310,7 @@ The usage of this notification has been removed since Neo4j 5.14. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.RuntimeExperimental |Title a|This feature is experimental and should not be used in production systems. @@ -1355,7 +1355,7 @@ It is important to change to the new functionality, otherwise, the query might b .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -1412,7 +1412,7 @@ If not intended for a composite database, escape the name with the character ``` CREATE DATABASE `foo.bar` ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1469,7 +1469,7 @@ UNION RETURN 'val' as one, 'val' as two ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1518,7 +1518,7 @@ warn: feature deprecated. The Unicode character `\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future. To continue using it, escape the identifier by adding backticks around the identifier `my\u0085identifier`. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1538,7 +1538,7 @@ The Unicode character `\u0085` is deprecated for unescaped identifiers and will .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -1597,7 +1597,7 @@ MATCH (a)-[:A|B|C]-() RETURN * ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1651,7 +1651,7 @@ SET a = properties(b) ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1708,7 +1708,7 @@ MATCH (a)-[r]-(b) SET a += properties(r) ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1764,7 +1764,7 @@ Instead, you can rewrite it to the following: MATCH (a: Start)-[r]->(b: End) RETURN b LIMIT 1 ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1818,7 +1818,7 @@ Alternatively, you can remove the runtime option to use the default runtime. MATCH (n) RETURN n ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1870,7 +1870,7 @@ Update the option `indexProvider` with the value `text-2.0`. CREATE TEXT INDEX FOR (n:Label) ON (n.prop) OPTIONS {indexProvider : 'text-2.0'} ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -1927,7 +1927,7 @@ Returned status description:: warn: feature deprecated without replacement. `unsupported.dbms.shutdown` is deprecated and will be removed without a replacement. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== [source,cypher] @@ -1992,7 +1992,7 @@ Returned status description:: warn: feature deprecated without replacement. `id` is deprecated and will be removed without a replacement. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: @@ -2601,7 +2601,7 @@ END AS check .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -2644,7 +2644,7 @@ Returned status description:: warn: feature deprecated without replacement. `connectComponentsPlanner` is deprecated and will be removed without a replacement. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -2666,7 +2666,7 @@ For more information, see link:https://neo4j.com/docs/cypher-manual/current/quer .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.FeatureDeprecationWarning |Title a|This feature is deprecated and will be removed in future versions. @@ -2691,7 +2691,7 @@ m|WARNING .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Request.DeprecatedFormat |Title a|The client made a request for a format which has been deprecated. @@ -2723,7 +2723,7 @@ Verify that this is the intended behavior of your query or command. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Security.CommandHasNoEffect |Title a|`` has no effect.* @@ -2771,7 +2771,7 @@ The role or privilege is not assigned. Suggestions for improvement:: Verify that this is the intended role and user. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -2816,7 +2816,7 @@ Suggestions for improvement:: Verify that this is the intended privilege and role. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -2843,7 +2843,7 @@ Verify that this is the intended privilege and role. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Security.CommandHasNoEffect |Title a|`` has no effect.* @@ -2892,7 +2892,7 @@ Suggestions for improvement:: Verify that this is the intended role and user. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -2937,7 +2937,7 @@ The role or privilege is already assigned. Suggestions for improvement:: Verify that this is the intended privilege and role. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -2966,7 +2966,7 @@ Verify that this is the intended privilege and role. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Security.ImpossibleRevokeCommand |Title a|`` has no effect.* @@ -3015,7 +3015,7 @@ This notification will become an error in a future major version. Suggestions for improvement:: Verify that this is the intended role and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3064,7 +3064,7 @@ o Suggestions for improvement:: Verify that this is the intended user and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3113,7 +3113,7 @@ This notification will become an error in a future major version. Suggestions for improvement:: Verify that this is the intended role and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3160,7 +3160,7 @@ This notification will become an error in a future major version. Suggestions for improvement:: Verify that this is the intended graph and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3208,7 +3208,7 @@ Suggestions for improvement:: Verify that this is the intended database and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3266,7 +3266,7 @@ Use `GRAPH *` without the parameter to revoke the privilege on all graphs. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Parameter:: + @@ -3332,7 +3332,7 @@ Suggestions for improvement:: Use `DATABASE *` without the parameter to revoke the privilege on all databases. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Parameter:: + @@ -3369,7 +3369,7 @@ Use `DATABASE *` without the parameter to revoke the privilege on all databases. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Security.AuthProviderNotDefined |Title a|The auth provider is not defined. @@ -3485,7 +3485,7 @@ If it is correct, make sure to add it as a known auth provider in one or both of .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Security.ExternalAuthNotEnabled |Title a|External auth for user is not enabled. @@ -3596,7 +3596,7 @@ Topology notifications provide additional information related to managing databa .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Cluster.ServerAlreadyEnabled |Title a| `` has no effect. @@ -3640,7 +3640,7 @@ Server `123e4567-e89b-12d3-a456-426614174000` is already enabled. Verify that this is the intended server. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3662,7 +3662,7 @@ Verify that this is the intended server. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Cluster.ServerAlreadyCordoned |Title a| `` has no effect. @@ -3706,7 +3706,7 @@ Server `123e4567-e89b-12d3-a456-426614174000` is already cordoned. Verify that this is the intended server. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3728,7 +3728,7 @@ Verify that this is the intended server. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Cluster.NoDatabasesReallocated |Title a| `` has no effect. @@ -3779,7 +3779,7 @@ For example, when there are three servers, each hosting databases `foo` and `bar For example, assuming server 1 hosts databases `foo` and `bar`, server 2 hosts only `foo`, and server 3 hosts no databases. Then, a better allocation would move `foo` from server 1 to server 3, but if server 3 has the constraint `deniedDatabases:['foo']}`, then the cluster is already balanced subject to this constraint. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: + @@ -3812,7 +3812,7 @@ For example, `CREATE DATABASE`, `ALTER DATABASE`, `DEALLOCATE DATABASES FROM SER .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Cluster.CordonedServersExistedDuringAllocation |Title a| Cordoned servers existed when making an allocation decision. @@ -3856,7 +3856,7 @@ Cordoned servers existed when making an allocation decision. Server(s) `123e4567-e89b-12d3-a456-426614174000` are cordoned. This can impact allocation decisions. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== The example assumes that you have a cluster with three servers, of which server `123e4567-e89b-12d3-a456-426614174000` is cordoned using the `dbms.cluster.cordonServer` procedure. Then the below command will return this notification. @@ -3879,7 +3879,7 @@ Server(s) `123e4567-e89b-12d3-a456-426614174000` are cordoned. This can impact a .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Cluster.RequestedTopologyMatchedCurrentTopology |Title a| `` has no effect. @@ -3925,7 +3925,7 @@ The requested topology matched the current topology. No allocations were changed. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== The example assumes that you have a cluster with three servers and a database `foo` with a topology of two primaries and one secondary. @@ -3952,7 +3952,7 @@ Schema notifications provide additional information related to indexes and const .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Schema.IndexOrConstraintAlreadyExists |Title a|`` has no effect. @@ -3997,7 +3997,7 @@ note: successful completion - index or constraint already exists. `RANGE INDEX existingRangeIndex FOR (e:Label) ON (e.property)` already exists. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Given a range index on `(:Label \{property})` named `existingRangeIndex`. @@ -4048,7 +4048,7 @@ CREATE TEXT INDEX myIndex2 IF NOT EXISTS FOR ()-[r:REL_TYPE]-() ON (r.property) ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Given a range index on `(:Label \{property})` named `myIndex`. @@ -4099,7 +4099,7 @@ note: successful completion - index or constraint already exists. `CONSTRAINT nodeKeyLabelPropertyConstraint FOR (e:Label) REQUIRE (e.property) IS NODE KEY` already exists. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Given a node key constraint on `(:Label \{property})` named `nodeKeyLabelPropertyConstraint`. @@ -4151,7 +4151,7 @@ CREATE CONSTRAINT myConstraint2 IF NOT EXISTS FOR (n:Label2) REQUIRE (n.property ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Given a node key constraint on `(:Label \{property})` named `myConstraint`. @@ -4185,7 +4185,7 @@ CREATE CONSTRAINT myConstraint2 IF NOT EXISTS FOR (n:Label2) REQUIRE (n.property .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Schema.IndexOrConstraintDoesNotExist |Title a|`` has no effect. @@ -4227,7 +4227,7 @@ Suggestions for improvement:: Verify that this is the intended index and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: @@ -4273,7 +4273,7 @@ Suggestions for improvement:: Verify that this is the intended constraint and that it is spelled correctly. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Command:: @@ -4306,7 +4306,7 @@ Verify that this is the intended constraint and that it is spelled correctly. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.SubqueryVariableShadowing |Title a|Variable in subquery is shadowing a variable with the same name from the outer scope. @@ -4367,7 +4367,7 @@ CALL { RETURN * ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -4408,7 +4408,7 @@ RETURN * .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.RedundantOptionalProcedure |Title a|The use of `OPTIONAL` is redundant when the procedure calls a void procedure. @@ -4451,7 +4451,7 @@ If the intended behavior of the query is to use a void procedure, the `OPTIONAL` CALL db.createLabel("A") ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -4479,7 +4479,7 @@ CALL db.createLabel("A") .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.RedundantOptionalSubquery |Title a|The use of `OPTIONAL` is redundant when `CALL` is a unit subquery. @@ -4529,7 +4529,7 @@ CALL (x) { } ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -4563,7 +4563,7 @@ CALL (x) { .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.ParameterNotProvided |Title a|The statement refers to a parameter that was not provided in the request. @@ -4609,7 +4609,7 @@ Provide the parameter(s). Suggestions for improvement:: Provide the parameter to be able to cache the plan. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -4636,7 +4636,7 @@ Provide the parameter to be able to cache the plan. .Notification details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Procedure.ProcedureWarning |Title a|The query used a procedure that generated a warning. @@ -4665,7 +4665,7 @@ When matching on a relationship type expression that can never be satisfied, for .Notification category details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.UnsatisfiableRelationshipTypeExpression |Title a|The query contains a relationship type expression that cannot be satisfied. @@ -4704,7 +4704,7 @@ Returned status description:: warn: unsatisfiable relationship type expression. The expression `R1&R2` cannot be satisfied because relationships must have exactly one type. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -4724,7 +4724,7 @@ Relationship type expression cannot possibly be satisfied. (`R1&R2` can never be .Notification category details [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code m|Neo.ClientNotification.Statement.RepeatedRelationshipReference |Title a|The query returns no results because a relationship variable is bound more than once. @@ -4773,7 +4773,7 @@ Use one pattern to match all relationships that start with a node with the label MATCH (:A)-[r]->(:B) RETURN r ---- ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + @@ -4813,7 +4813,7 @@ Returned status description:: warn: repeated relationship reference. `r` is repeated in `()-[r*]->()<-[r*]-()`, which leads to no results. ====== -[.include-with-neo4j-legacy-code] +[.include-with-neo4j--code] ====== Query:: + diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index e3aabf47..f63a3c57 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -1,15 +1,15 @@ -:description: The Neo4j notifications for Neo4j version {neo4j-version}. +:description: Server notifications for Neo4j version {neo4j-version}. [[notifications]] = Server notifications After a successful query execution, the Neo4j server sends notifications to provide advice on how to improve the query's quality or give additional information about the query execution. -The driver receives these notifications and sends them to the client (e.g. Browser/Bloom/Cypher Shell), which displays them to the user. +The driver receives these notifications and sends them to the Neo4j tools (e.g. Browser, Bloom, Cypher Shell) or the user application, which display them to the user. From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API (deprecated since 5.26). The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. -This page describes both the GQL-status object and the Neo4j Notification frameworks, how they are structured, the objects they provide for notifications, and how to interpret them. +This page describes the GQL-status object and the Neo4j notification frameworks, their structure, the objects they provide for notifications, and how to interpret them. It also explains the server notification grouping and filtering, the notification internals, and the server-driver compatibility for both the Notification and GqlStatusObject APIs. [role=label--version-5.23] @@ -154,18 +154,18 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their |=== [role=label--deprecated-5.26] -[[legacy-notification-object]] -== Legacy notification object +[[-notification-object]] +== notification object -The Neo4j legacy notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. +The Neo4j notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. Depending on the application, some of the fields from the notification object might not be visible. -The legacy notification object consists of the following fields: +The notification object consists of the following fields: -.Neo4j legacy notification object +.Neo4j notification object [cols="<1s,<4"] |=== -|Neo4j legacy code +|Neo4j code a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. |Title a|The title of the Neo4j status code. @@ -262,7 +262,7 @@ On the server side, notifications are part of the Result Core API. A method called `getNotifications()`, which is deprecated since 5.26, returns a list of server-side notification objects. These notifications are then sent to the driver as success Bolt message metadata. On the driver side, notifications are part of the ResultSummary API, which has a method called `notifications()` that returns a list of driver-side Notification objects. -The result of the `getCode()` or `code()` methods is known as the legacy Neo4j status code. +The result of the `getCode()` or `code()` methods is known as the Neo4j status code. Driver-side notification configuration filters notifications by severity and/or category at both the driver and session levels. For more information, see <>. From 77b843e090a58af79c842705c338efc445c57006 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 27 Nov 2024 10:54:52 +0000 Subject: [PATCH 13/29] remove server from headings --- modules/ROOT/pages/errors/gql-errors.adoc | 2 +- modules/ROOT/pages/notifications/all-notifications.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/errors/gql-errors.adoc b/modules/ROOT/pages/errors/gql-errors.adoc index 77a85ef4..2555bcdc 100644 --- a/modules/ROOT/pages/errors/gql-errors.adoc +++ b/modules/ROOT/pages/errors/gql-errors.adoc @@ -1,7 +1,7 @@ :description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur. [[neo4j-gqlstatus-errors]] -= List of GQLSTATUS server error codes += List of GQLSTATUS error codes //The following page provides an overview of all server errors in Neo4j, along with some scenarios and their possible solutions. The following page provides an overview of all GQLSTATUS server error codes in Neo4j. diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 53879f26..7b18017c 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -1,7 +1,7 @@ :description: This section describes the notifications that Neo4j can return, grouped by category, and an example of when they can occur. [[listOfNnotifications]] -= List of all server notification codes += List of notification codes The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and Neo4j codes, along with some scenarios and their possible solutions. From e666f2e17ab5d8f64b70615e5959c5f37dc1f763 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 28 Nov 2024 09:16:04 +0000 Subject: [PATCH 14/29] Update modules/ROOT/pages/errors/index.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Antonio Barcélos --- modules/ROOT/pages/errors/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index ae9cc7b7..ba88833f 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -174,7 +174,7 @@ See <> for mor On the driver side, the Neo4jException is extended with the corresponding methods as on the server side. The driver receives the Failure Bolt message and extracts the status code and the error message. -Then, it constructs an error object with the status code, error message, and other relevant information, and sends it to the client. +Then, it constructs an exception with the status code, error message, and other relevant information, and sends it to the client. // Starting from 2025.01, the diagnostic record also contains a `_status_parameters` field, which represens a map that contains all variable parts of the status description, such as labels, database names, Cypher clauses, etc. // This field is used to provide more detailed information about the error. From edb0d38def34954767492fa79cf34381689710bf Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 28 Nov 2024 11:11:39 +0000 Subject: [PATCH 15/29] Further updates based on feedback --- modules/ROOT/pages/changelogs.adoc | 7 --- modules/ROOT/pages/errors/all-errors.adoc | 8 +-- modules/ROOT/pages/errors/index.adoc | 57 ++++++++++----------- modules/ROOT/pages/index.adoc | 2 +- modules/ROOT/pages/notifications/index.adoc | 41 +++++++-------- 5 files changed, 50 insertions(+), 65 deletions(-) diff --git a/modules/ROOT/pages/changelogs.adoc b/modules/ROOT/pages/changelogs.adoc index 03175695..64aba7d4 100644 --- a/modules/ROOT/pages/changelogs.adoc +++ b/modules/ROOT/pages/changelogs.adoc @@ -1,15 +1,8 @@ :description: This page lists all changes to status codes per Neo4j version. = Changes to status codes per Neo4j version -== Neo4j 5.26 - -**Changed:** -Using differently ordered return items in a `UNION [ALL]` clause has been undeprecated following cost-benefit analysis and valuable user feedback. - == Neo4j 5.25 -**New:** - Starting from 5.25, the query log includes the GQL error information under the JSON object `errorInfo`. For more information, see link:https://neo4j.com/docs/operations-manual/current/monitoring/logging/#gql-error-information[Operations Manual -> GQL error information]. diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 8963dcf6..622193eb 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -2,13 +2,13 @@ [[neo4j-errors]] -= List of Neo4j codes += List of Neo4j error codes This page lists the current Neo4j error codes, which will be replaced by xref:errors/gql-errors.adoc[GQLSTATUS error codes] in the future. Error codes are returned by the server when the execution of a query fails. They always have the severity level `ERROR`. -Errors are grouped based on the type of the Neo4j status code: +Errors are grouped based on the type of the Neo4j code: Client errors:: These errors are caused by the client (user input or user application) and are usually related to the request itself. @@ -17,11 +17,11 @@ The Neo4j codes for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. The error can be temporary, and the request could succeed if retried. -The Neo4j status codes for transient errors have the prefix Neo.`TransientError`. +The Neo4j codes for transient errors have the prefix Neo.`TransientError`. Database errors:: These errors are caused by the database and are usually related to the database state. -The Neo4j status codes for database errors have the prefix `Neo.DatabaseError`. +The Neo4j codes for database errors have the prefix `Neo.DatabaseError`. This page contains lists of all Neo4j errors, grouped by type. diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index ba88833f..05a79977 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -3,31 +3,37 @@ = Server errors The Neo4j DBMS returns a server error to indicate that the outcome of a Cypher query or command execution is unsuccessful. +The driver receives these erors and sends them to the Neo4j tools (e.g. Browser, Bloom, Cypher Shell) or the user application, which display them to the user. -Starting from version 5.25, the Neo4j error codes have an additional GQL-status object along with the Neo4j exception that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. +Starting from version 5.26, the Neo4j error codes have an additional GQL-status object along with the Neo4j exception that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. +This additional GQL-status object is also displayed in the query log from Neo4j 5.25. +For more information, see link:https://neo4j.com/docs/operations-manual/current/monitoring/logging/#gql-error-information[Operations Manual -> GQL error information]. [NOTE] ==== -This additional GQL-status object is currently displayed only in the query log. -For more information, see link:https://neo4j.com/docs/operations-manual/current/monitoring/logging/#gql-error-information[Operations Manual -> GQL error information]. +The default GQLSTATUS code 50N42 is returned when an exception does not have a GQL-status object. +Starting from Neo4j 5.25, we started adding GQL objects to exceptions. +Therefore, you can expect many 50N42 codes during this transition period. +However, it is important not to rely on this default code, as future Neo4j versions might change it by adding an appropriate GQL object to the exception. +Additionally, GQL codes for external procedures are not yet stable. ==== -This page describes the GQL-status object and the Neo4j error frameworks, their structure, the objects they provide for errors, and how to interpret them. -It also explains the error internals and the server-driver compatibility for both the GQLSTATUS and errors. +This page describes the GQL-status and the Neo4j-status object frameworks for errors, their structure, the objects they provide for errors, and how to interpret them. +It also explains the error internals and the server-driver compatibility for both the GQLSTATUS and errors. [role=label--version-5.25] [[gqlstatus-error-object]] == GQL-status error object -In the GQL-status object framework, errors are an implementation-defined subset of the GQL-status objects that cover exceptions. - -In GQL, the execution of a query from user to server always has an outcome, called the _execution outcome_. -The execution outcome is a list of GQL-status objects ordered by the following precedence rules: +In the GQL-status object framework, when a user executes a query to the server, it always produces a result known as the _execution outcome_. +If an error occurs during execution, the outcome is recorded as an exception condition, indicating a failed outcome with no result. +The execution outcome for errors is represented as a list of GQL-status objects with a failed outcome, which are organized according to the following precedence rules: . Every exception that results in a transaction rollback takes precedence over other exceptions. . Every exception takes precedence over any completion condition. +For completion conditions, see the xref:notifications/index.adoc#gqlstatus-notification-object[GQL-status notification object]. -The GQL-status object also includes the Neo4j-specific information, such as the severity level and the error classification. +The GQL-status object also includes Neo4j-specific information, such as severity level and error classification. Each GQL-status object consists of the following fields: @@ -39,10 +45,11 @@ a| A 5-character string that is the concatenation of a 2-character class code fo |StatusDescription a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and an optional additional text about the condition. The condition and subcondition are textual representations of the class and subclass codes, respectively. +The format is `error: condition - subcondition. AdditionalInfo`. The subcondition for the subclass 000 is empty. | DiagnosticRecord a| Extra information about the status, given as key-value pairs, both on the server and driver side. -To retrieve the full diagnostic record, you can use the `diagnosticRecord()` method on both the server and driver sides. +To retrieve the full diagnostic record, you can use the `diagnosticRecord()` on the server side or the corresponding method on the driver sides. Additional helper methods are exposed for some useful fields. [cols="<1s,<4"] !=== @@ -57,8 +64,7 @@ Additional helper methods are exposed for some useful fields. !=== |=== -A GQL-status error object can also contain an optional wrapped GQL-status object. -This wrapped object is referred to as a `cause` and used to provide additional, more specific diagnostic information. +A GQL-status error object can also contain an optional GQL-status object that represents the cause of the error and is used to provide additional, more specific diagnostic information. [[gqlstatus-neo4j-defined-codes]] == Classes of GQLSTATUS error codes @@ -66,7 +72,7 @@ This wrapped object is referred to as a `cause` and used to provide additional, The GQLSTATUS codes are divided into classes and subclasses. The class code is a 2-character string that indicates the general condition of the status, such as connection exception, data exception, etc. The subclass code is a 3-character string that provides more detailed information about the condition. -The Neo4j-define subclasses start with N, followed by a 2-digit number, while the ones that do not start with N are standard-defined subclasses. +//Currently, the Neo4j-defined subclasses start with N or I, followed by a 2-digit number, while the standard-defined subclasses start with 0-4 or A, B, C, D, E, F, G, or H and a 2-digit number. The following table lists the GQLSTATUS classes and their meanings: @@ -94,10 +100,10 @@ The following table lists the GQLSTATUS classes and their meanings: | procedure exception |=== -[[-error-object]] -== Neo4j error object +[[neo4j-error-object]] +== Neo4j-status error object -The Neo4j error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. +The Neo4j-status object for errors contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant. Depending on the application, some of the fields from the error object might not be visible. The error object consists of the following fields: @@ -164,8 +170,8 @@ Most of these implement the `HasStatus` interface, which means they have a statu On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the status code. -Starting from 5.25, the exceptions also get new compulsary fields for `gqlStatus`, `statusDescription`, `diagnosticRecord`, and an optional field for `cause`. -The cause field is a wrapped underlying Neo4j exception, which in turn has its own GQLSTATUS, statusdescription, diagnostic record, and message. + +The exceptions also get new compulsary fields for `gqlStatus`, `statusDescription`, `diagnosticRecord`, and an optional field for `cause`. +The cause field in turn has its own GQLSTATUS, statusdescription, diagnostic record, and message. + The `getMessage()` method is kept as Java exceptions inherently have this method. And a new classification field is added to cover the division of client errors, transient errors, and database errors, which today is part of the Neo4j code. All of these fields construct the GQLSTATUS object, which is sent to the driver as part of the Failure Bolt message. @@ -186,18 +192,9 @@ As the clients can have separate driver versions, they may have different error In Neo4j 5.25, the default JSON template for the query log is updated to include `errorInfo` entry. This entry contains `GQLSTATUS`, `statusDescription`, `classification`, `position` (if applicable), and `cause` (if applicable) with the same entries. -The `failureReason` entry is deprecated from 5.26. - -[NOTE] -==== -The default GQLSTATUS code 50N42 is returned when an exception does not have a GQL-status object. -Starting from Neo4j 5.25, we started adding GQL objects to exceptions. -Therefore, you can expect many 50N42 codes during this transition period. -However, it is important not to rely on this default code, as future Neo4j versions might change it by adding an appropriate GQL object to the exception. -Additionally, GQL codes for external procedures are not yet stable. -==== +//The `failureReason` entry is deprecated from ... -// Starting from Neo4j 2025.01, a new JSON template is available for the query log, which is the default set in server_log.xml. +// Starting from Neo4j 2025.01, a new JSON template is available for the query log, which is the default set in _server_log.xml_. // It contains the `errorInfo` entry, but not the `failureReason` entry, which is switched off by default. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 3adbb30a..b35eba29 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -9,7 +9,7 @@ endif::[] :description: Status codes for errors and notifications Neo4j 5 :neo4j-buildnumber: {neo4j-version} -This manual provides status codes for errors and notifications that a Neo4j server may return to indicate the result of a Cypher request. +This manual covers all status codes for errors and notifications that a Neo4j server may return to indicate the result of a Cypher request. Starting from 5.23 for notifications and 5.25 for errors, the Neo4j DBMS supports the GQL standard. + GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases. diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index f63a3c57..e1c2cd53 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -3,43 +3,38 @@ [[notifications]] = Server notifications -After a successful query execution, the Neo4j server sends notifications to provide advice on how to improve the query's quality or give additional information about the query execution. +After a successful query execution, the Neo4j server sends notifications to give additional information about the query execution or provide advice on how to improve the query's quality. The driver receives these notifications and sends them to the Neo4j tools (e.g. Browser, Bloom, Cypher Shell) or the user application, which display them to the user. From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API (deprecated since 5.26). The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. -This page describes the GQL-status object and the Neo4j notification frameworks, their structure, the objects they provide for notifications, and how to interpret them. +This page describes the GQL-status object and the Neo4j notification frameworks, their structure, the objects they provide for notification, and how to interpret them. It also explains the server notification grouping and filtering, the notification internals, and the server-driver compatibility for both the Notification and GqlStatusObject APIs. [role=label--version-5.23] [[gqlstatus-notification-object]] == GQL-status notification object -In the GQL-status object framework, notifications are an implementation-defined subset of the GQL-status objects that cover informational notes and warnings, but not errors, `SUCCESS`, `NO DATA`, or `OMITTED RESULT`. -For the latter, see <>. + - -In GQL, the execution of a query from user to server always has an outcome, called the _execution outcome_. -The execution outcome is a list of GQL-status objects, ordered by the following precedence, where the first object in the list is the primary GQL-status object: +In the GQL-status object framework, when a user executes a query to the server, it always produces a result known as the _execution outcome_. +If no error occurs during execution, the outcome is recorded as a completion condition, indicating a successful result with a regular non-empty result, an omitted result, or no data. +It is represented as a list of GQL-status objects, which are organized according to the following precedence rules, where the first object in the list is the primary GQL-status object: . `NO DATA` has precedence over `WARNING`. . `WARNING` has precedence over the `SUCCESSFUL COMPLETION` subclass. . `SUCCESSFUL COMPLETION` subclass has precedence over `INFORMATIONAL`. . `INFORMATIONAL` is the condition with the least precedence. +For more information about `SUCCESSFUL COMPLETION`, `NO DATA`, or `OMITTED RESULT`, see <>. + +The GQL-status object can contain multiple GQL-status objects, where each object represents a different condition of the query execution. The primary GQL-status object describes the condition with the greatest precedence and is always present. All other GQL-status objects in the list are additional GQL-status objects. -The GQL-status object also includes the Neo4j-specific information, such as the severity level and the classification of the notification, which can be used for filtering. +The GQL-status object also includes Neo4j-specific information, such as severity level and notification classification, which can be used for filtering. For more information about notification grouping and filtering, see <>. Each GQL-status object consists of the following fields: -— A GQLSTATUS, which is a character string identifying a condition as defined in Subclause 23.1, -“GQLSTATUS”. -— A status description, which is a character string describing the GQLSTATUS. -— A record with diagnostic information as defined in Subclause 23.2, “Diagnostic records”. -— An optional nested GQL-status object for providing additional diagnostic information, such as a -cause. + .GQLSTATUS notification object [cols="<1s,<4"] |=== @@ -50,7 +45,7 @@ a| A human-readable description of the GQLSTATUS, which consists of a condition, The condition and subcondition are textual representations of the class and subclass codes, respectively. | DiagnosticRecord a| Extra information about the status, given as key-value pairs, both on the server and driver side. -To retrieve the full diagnostic record, you can use the `diagnosticRecord()` method on both the server and driver sides. +To retrieve the full diagnostic record, you can use the `diagnosticRecord()` on the server side or the corresponding method on the driver sides. Additional helper methods are exposed for some useful fields. [cols="<1s,<4"] !=== @@ -154,21 +149,21 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their |=== [role=label--deprecated-5.26] -[[-notification-object]] -== notification object +[[neo4j-notification-object]] +== Neo4j-status notification object -The Neo4j notification object contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. +The Neo4j-status object for notifications contains diagnostic information representing the successful outcome of a Cypher query or command execution, including severity, the `ClientNotification` code, category, title, description, and position in the query text where the notification is relevant. Depending on the application, some of the fields from the notification object might not be visible. -The notification object consists of the following fields: +The notification object consists of the following fields: -.Neo4j notification object +.Neo4j notification object [cols="<1s,<4"] |=== -|Neo4j code -a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. +|Neo4j code +a|The Neo4j code in the form of `Neo.ClientNotification.[SubType].[Name]`. |Title -a|The title of the Neo4j status code. +a|The title of the Neo4j code. |Description a|The description of the specific notification. |Severity level From 0a43d3d5e1534faad3dc5297a2f4e8b5115b86a8 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 28 Nov 2024 14:34:34 +0000 Subject: [PATCH 16/29] fix the link to the Cypher Manual --- modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index b35eba29..ce5f4117 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -14,7 +14,7 @@ This manual covers all status codes for errors and notifications that a Neo4j se Starting from 5.23 for notifications and 5.25 for errors, the Neo4j DBMS supports the GQL standard. + GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases. Cypher®, Neo4j’s query language, supports most mandatory and a substantial portion of the optional GQL features (as defined by the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]). -For more information, see link:https:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance]. +For more information, see link:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance]. As part of this GQL compliance, Cypher now also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. For more information on the GQL-status object framework for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. From 9097481d08dcde10fb6fe5d634677808540aeefe Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:50:57 +0000 Subject: [PATCH 17/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 622193eb..37040219 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -32,7 +32,7 @@ This is a complete list of all client errors Neo4j may return, and what they mea [options="header", cols="<1m,<1"] |=== -| Neo4j code +| Neo4j code | Description | Neo.ClientError.ChangeDataCapture.InvalidIdentifier From 9be9ba072c73c867f4283d01d314e0ca79242a9c Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:53:48 +0000 Subject: [PATCH 18/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 37040219..8ea30036 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -298,7 +298,7 @@ This is a complete list of all transient errors Neo4j may return, and what they [options="header", cols="<1m,<1"] |=== -| Neo4j code +| Neo4j code | Description | Neo.TransientError.ChangeDataCapture.FutureIdentifier From 92a67c4e9d2799f2cc4c0bebaf5b64fca467ffe3 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:53:56 +0000 Subject: [PATCH 19/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 8ea30036..a545e127 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -405,7 +405,7 @@ This is a complete list of all database errors Neo4j may return, and what they m [options="header", cols="<1m,<1"] |=== -| Neo4j code +| Neo4j code | Description | Neo.DatabaseError.ChangeDataCapture.Disabled From a2940f0a11147b619ae77097c1786bfb76c9b384 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:54:13 +0000 Subject: [PATCH 20/29] Update modules/ROOT/pages/errors/all-errors.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index a545e127..6de5154e 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -17,7 +17,7 @@ The Neo4j codes for client errors have the prefix `Neo.ClientError`. Transient errors:: These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. The error can be temporary, and the request could succeed if retried. -The Neo4j codes for transient errors have the prefix Neo.`TransientError`. +The Neo4j codes for transient errors have the prefix `Neo.TransientError`. Database errors:: These errors are caused by the database and are usually related to the database state. From 5734458564075f1482b1c9c8b137fbfb2dff7130 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:54:35 +0000 Subject: [PATCH 21/29] Update modules/ROOT/pages/errors/index.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index 05a79977..54afc19b 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -190,7 +190,7 @@ Then, it constructs an exception with the status code, error message, and other Since the query log is server-side and DBMS wide, multiple clients connected to the same DBMS write to the same query log. As the clients can have separate driver versions, they may have different error framework formats. -In Neo4j 5.25, the default JSON template for the query log is updated to include `errorInfo` entry. +In Neo4j 5.25, the default JSON template for the query log is updated to include an `errorInfo` entry. This entry contains `GQLSTATUS`, `statusDescription`, `classification`, `position` (if applicable), and `cause` (if applicable) with the same entries. //The `failureReason` entry is deprecated from ... From d27ad0e0921731b106ea26e4da0d55bd25c37492 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:54:52 +0000 Subject: [PATCH 22/29] Update modules/ROOT/pages/index.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index ce5f4117..44293f62 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -16,7 +16,7 @@ GQL is the new link:https://www.iso.org/home.html[ISO] International Standard qu Cypher®, Neo4j’s query language, supports most mandatory and a substantial portion of the optional GQL features (as defined by the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]). For more information, see link:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance]. -As part of this GQL compliance, Cypher now also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. +As part of this GQL compliance, Cypher also includes status codes that a GQL-compliant DBMS returns to indicate the outcome of a request. For more information on the GQL-status object framework for notifications and errors, see xref:notifications/index.adoc[] and xref:errors/index.adoc[]. ifndef::backend-pdf[] From d7a7effc2ac78adce7e6475899e0ab87ccc1af50 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:55:04 +0000 Subject: [PATCH 23/29] Update modules/ROOT/pages/notifications/all-notifications.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/notifications/all-notifications.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 7b18017c..e7807fb5 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -3,7 +3,7 @@ [[listOfNnotifications]] = List of notification codes -The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and Neo4j codes, along with some scenarios and their possible solutions. +The following page provides an overview of all notifications in Neo4j, including the GQLSTATUS codes and Neo4j codes, along with some scenarios and their possible solutions. * <<_performance_notifications, `PERFORMANCE` notifications>> * <<_hint_notifications, `HINT` notifications>> From 3addd2d21a2fee7f5955d35f09a022f0c7dad32c Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:55:12 +0000 Subject: [PATCH 24/29] Update modules/ROOT/pages/notifications/all-notifications.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/notifications/all-notifications.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index e7807fb5..602a1237 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -29,7 +29,7 @@ This notification is returned when there is a Cartesian product in the plan. .Notification details [cols="<1s,<4"] |=== -|Neo4j code +|Neo4j code m|Neo.ClientNotification.Statement.CartesianProduct |Title a|This query builds a cartesian product between disconnected patterns. From dffd0783d47797e83e3ad46e0c842248bdda48e8 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:55:24 +0000 Subject: [PATCH 25/29] Update modules/ROOT/pages/notifications/index.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/notifications/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index e1c2cd53..e78ff170 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -257,7 +257,7 @@ On the server side, notifications are part of the Result Core API. A method called `getNotifications()`, which is deprecated since 5.26, returns a list of server-side notification objects. These notifications are then sent to the driver as success Bolt message metadata. On the driver side, notifications are part of the ResultSummary API, which has a method called `notifications()` that returns a list of driver-side Notification objects. -The result of the `getCode()` or `code()` methods is known as the Neo4j status code. +The result of the `getCode()` or `code()` methods is known as the Neo4j status code. Driver-side notification configuration filters notifications by severity and/or category at both the driver and session levels. For more information, see <>. From 9c409e8d9847a38a336d80838c2bb5fc5f25748b Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:55:40 +0000 Subject: [PATCH 26/29] Update modules/ROOT/pages/errors/index.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index 54afc19b..96528f4c 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -152,7 +152,7 @@ Changing the request might yield a successful outcome. | TransientError | These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc. The error can be temporary, therefore retrying later might yield a successful outcome. -Neo4j codes have the prefix Neo.`TransientError`, while the GQLSTATUS codes have `ErrorClassification` of type `TRANSIENT_ERROR`. +Neo4j codes have the prefix `Neo.TransientError`, while the GQLSTATUS codes have `ErrorClassification` of type `TRANSIENT_ERROR`. | Rollback | DatabaseError From 4f63dfdafbf65abe5c099a55ecf1bde2e929bb28 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 08:55:58 +0000 Subject: [PATCH 27/29] Update modules/ROOT/pages/errors/index.adoc Co-authored-by: Hannes Voigt <30618026+hvub@users.noreply.github.com> --- modules/ROOT/pages/errors/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index 96528f4c..d4179c83 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -171,7 +171,7 @@ Most of these implement the `HasStatus` interface, which means they have a statu On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the status code. The exceptions also get new compulsary fields for `gqlStatus`, `statusDescription`, `diagnosticRecord`, and an optional field for `cause`. -The cause field in turn has its own GQLSTATUS, statusdescription, diagnostic record, and message. + +The cause field in turn has its own GQLSTATUS, status description, diagnostic record, and message. + The `getMessage()` method is kept as Java exceptions inherently have this method. And a new classification field is added to cover the division of client errors, transient errors, and database errors, which today is part of the Neo4j code. All of these fields construct the GQLSTATUS object, which is sent to the driver as part of the Failure Bolt message. From 18db25059ff76a867674b3d131345fa018ca6221 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 11:13:00 +0000 Subject: [PATCH 28/29] apply suggestions from review --- modules/ROOT/pages/errors/all-errors.adoc | 2 +- modules/ROOT/pages/errors/index.adoc | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 6de5154e..8e119cc3 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -4,7 +4,7 @@ [[neo4j-errors]] = List of Neo4j error codes -This page lists the current Neo4j error codes, which will be replaced by xref:errors/gql-errors.adoc[GQLSTATUS error codes] in the future. +This page lists the current Neo4j error codes, which which are returned along side xref:errors/gql-errors.adoc[GQLSTATUS error codes]. Error codes are returned by the server when the execution of a query fails. They always have the severity level `ERROR`. diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index d4179c83..f440d4c0 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -6,7 +6,7 @@ The Neo4j DBMS returns a server error to indicate that the outcome of a Cypher q The driver receives these erors and sends them to the Neo4j tools (e.g. Browser, Bloom, Cypher Shell) or the user application, which display them to the user. Starting from version 5.26, the Neo4j error codes have an additional GQL-status object along with the Neo4j exception that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. -This additional GQL-status object is also displayed in the query log from Neo4j 5.25. +This additional GQL-status object is also displayed in the query log from Neo4j 5.25 onwards. For more information, see link:https://neo4j.com/docs/operations-manual/current/monitoring/logging/#gql-error-information[Operations Manual -> GQL error information]. [NOTE] @@ -160,6 +160,9 @@ Neo4j codes have the prefix `Neo.TransientError`, while the GQLSTATUS codes have Neo4j codes have the prefix `Neo.DatabaseError`, while the GQLSTATUS codes have `ErrorClassification` of type `DATABASE_ERROR`. | Rollback +// | Database configuration errors +// | Something a DBA can fix +// | Rollback |=== [[error-internals]] From b772532fb6da4676df0aed87c22c673f63ae2218 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 29 Nov 2024 11:14:17 +0000 Subject: [PATCH 29/29] remove DBMS --- modules/ROOT/pages/errors/index.adoc | 2 +- modules/ROOT/pages/index.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/errors/index.adoc b/modules/ROOT/pages/errors/index.adoc index f440d4c0..c9bc77b9 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -2,7 +2,7 @@ [[neo4j-errors]] = Server errors -The Neo4j DBMS returns a server error to indicate that the outcome of a Cypher query or command execution is unsuccessful. +Neo4j returns a server error to indicate that the outcome of a Cypher query or command execution is unsuccessful. The driver receives these erors and sends them to the Neo4j tools (e.g. Browser, Bloom, Cypher Shell) or the user application, which display them to the user. Starting from version 5.26, the Neo4j error codes have an additional GQL-status object along with the Neo4j exception that provides information about the status of a Cypher query or command execution in compliance with the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 44293f62..e67ac011 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -11,7 +11,7 @@ endif::[] This manual covers all status codes for errors and notifications that a Neo4j server may return to indicate the result of a Cypher request. -Starting from 5.23 for notifications and 5.25 for errors, the Neo4j DBMS supports the GQL standard. + +Starting from 5.23 for notifications and 5.25 for errors, Neo4j supports the GQL standard. + GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases. Cypher®, Neo4j’s query language, supports most mandatory and a substantial portion of the optional GQL features (as defined by the link:https://www.iso.org/standard/76120.html[ISO/IEC 39075:2024(en) - Information technology - Database languages - GQL Standard]). For more information, see link:https://neo4j.com/docs/cypher-manual/current/appendix/gql-conformance/[Cypher Manual -> GQL conformance].