GQL framework

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

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
 

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,30 +44,31 @@ 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
 
 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:
 
 .GQLSTATUS code classes
 [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 <<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.
+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.

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]

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 <<notification-grouping-and-filtering>>.
 
 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 <<notification-grouping-and-filtering, Server notification grouping and filtering>>.