Add more information to the gql frameworks

Author: renetapopova

modules/ROOT/pages/draft.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,48 +113,88 @@ 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
 
 |===
 
 [[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 <<server-driver-compatibility, Server-driver version compatibility>> 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
+== 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].
+
+

modules/ROOT/pages/errors/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.