From 257d2d0bf503d0397c34f026e9430e7dab1784b5 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 5 Aug 2024 14:00:21 +0100 Subject: [PATCH 01/12] first draft of the notification framework --- modules/ROOT/pages/notifications/index.adoc | 97 +++++++++++++++++---- 1 file changed, 78 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 8d165e74..0fd4ed1b 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -1,35 +1,79 @@ :description: The Neo4j notifications for Neo4j version {neo4j-version}. [[notifications]] -= Notification codes += Returned server notifications -Notification codes are Neo4j status codes of type `ClientNotification`and are returned by the server with severity `WARNING` or `INFORMATION`. -Contrary to errors, notifications are only returned if the execution of the query is successful. +The Neo4j server returns codes of type `ClientNotification` in response to successful query execution. +All notifications have a severity level, which can be `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION` and can be used to improve the quality of the query or to provide additional information about the query execution. -[[notification-format]] -== Notification object fields +From Neo4j 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j codes. +GQLSTATUS codes are returned as part of the result summary and provide diagnostic information about the status of a Cypher query or command execution, including the outcome of the execution (successful completion, warnings, no data, information), the diagnostic code, and the diagnostic message. -The notification object, which is part of the result summary, consists of the following fields: +The following sections describe the Neo4j and the GQLSTATUS notification codes. + +[[notification-object]] +== Notification object + +The notification object contains diagnostic information representing the status of a Cypher query or command execution, including the outcome of the execution, the diagnostic code, and the diagnostic message. +The notification object is part of the result summary and is returned by the server with severity `WARNING` or `INFORMATION`. + +The notification object consists of the following fields: + +[.tabbed-example] +===== +[.include-with-neo4j-code] +====== -* *Code* -- The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. -* *Title* -- The description of the Neo4j status code. -* *Description* -- The description of a specific notification, which can contain details about the query being executed. -* *Severity* -- 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* -- The category of the notification. -* *Position* -- The position, given by row and column, where the notification is relevant in the query text. +[cols="<1s,<4"] +|=== +|Neo4j code +a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. +|Title +a|The description of the Neo4j status code. +|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. +|=== +====== + +[.include-with-GQLSTATUS-code] +====== +[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. +|Status description +a| +|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. +|Classification +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-categories]] -== Notification code categories +== Notification code grouping -All notifications are grouped by category, which can have severity `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. +All Neo4j notification codes are grouped by category/classification and severity `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. -The following categories exist, ordered by severity: +The following groups exist, ordered by severity: +.Neo4j notification categories [options="header", cols="<1m,<1m,<3,<2"] |=== -| CATEGORY +| CATEGORY/CLASSIFICATION | SEVERITY | EXPLANATION | RECOMMENDED ACTION @@ -78,4 +122,19 @@ The following categories exist, ordered by severity: | INFORMATION | The query uses costly operations and might be slow. Consider if it is possible to rewrite the query in a different way. | -|=== \ No newline at end of file +|=== + +[[role=label--version-5.23]] +[[gqlstatus-codes]] +== GQLSTATUS notifications + + + + +[[gqlstatus-notification-format]] +== GQL-status object + +In full, the execution outcome succeeds or fails, GQL mandates that it contains an object, called a GQL-status object, representing the diagnostic information. The GQL-status object can be also accompanied with a list of other additional GQL-status objects describing additional diagnostic information related to the execution of the same GQL-request. The list is empty by default, unless the implementation chooses to make the additional GQL-status objects available. The main GQL-status object is called the primary GQL-status object. +are the GQLSTATUS code and the status description. +The notification object, which is part of the result summary, consists of the following fields: + From 65de76349fa4f92ca3019d7f5d00208430fb4ac4 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 12:04:42 +0100 Subject: [PATCH 02/12] add information about GQL-status objetc, codes, etc --- modules/ROOT/pages/changelogs.adoc | 7 + modules/ROOT/pages/errors/all-errors.adoc | 2 +- modules/ROOT/pages/errors/index.adoc | 4 +- modules/ROOT/pages/index.adoc | 7 + .../notifications/all-notifications.adoc | 2 +- modules/ROOT/pages/notifications/index.adoc | 217 ++++++++++++++---- 6 files changed, 194 insertions(+), 45 deletions(-) diff --git a/modules/ROOT/pages/changelogs.adoc b/modules/ROOT/pages/changelogs.adoc index 2c60c782..f4a07560 100644 --- a/modules/ROOT/pages/changelogs.adoc +++ b/modules/ROOT/pages/changelogs.adoc @@ -1,6 +1,13 @@ :description: This page lists all changes to status codes per Neo4j version. = Changes to status codes per Neo4j version +== Neo4j 5.23 + +From version 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j `ClientNotification` codes when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + +GQLSTATUS codes provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. +It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. +For more information, see xref:notifications/index.adoc[Server notifications] and xref:notifications/all-notifications.adoc[List of all server notification codes]. + == Neo4j 5.17 **New:** diff --git a/modules/ROOT/pages/errors/all-errors.adoc b/modules/ROOT/pages/errors/all-errors.adoc index 7f6dcc69..28942cd0 100644 --- a/modules/ROOT/pages/errors/all-errors.adoc +++ b/modules/ROOT/pages/errors/all-errors.adoc @@ -2,7 +2,7 @@ [[neo4j-errors]] -= List of all error codes += List of all server error codes 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 f11d8ece..4d6e4637 100644 --- a/modules/ROOT/pages/errors/index.adoc +++ b/modules/ROOT/pages/errors/index.adoc @@ -1,7 +1,7 @@ :description: The Neo4j error codes for Neo4j version {neo4j-version}. -[[notifications]] -= Error codes +[[error-codes]] += Server errors Error codes are Neo4j status codes returned by the server when the execution of a query fails. They always have the severity level `ERROR`. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index ae9d0236..02c519e1 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -55,6 +55,13 @@ The type of the status code determines the effect on the transaction. |=== +[NOTE] +==== +From version 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j `ClientNotification` codes when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + +GQLSTATUS codes provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. +It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. +For more information, see xref:notifications/index.adoc[Server notifications]. +==== 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 0f600912..bee9bd23 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 notification codes += 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. diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 0fd4ed1b..12724f36 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -1,29 +1,26 @@ :description: The Neo4j notifications for Neo4j version {neo4j-version}. [[notifications]] -= Returned server notifications += Server notifications -The Neo4j server returns codes of type `ClientNotification` in response to successful query execution. -All notifications have a severity level, which can be `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION` and can be used to improve the quality of the query or to provide additional information about the query execution. +The Neo4j server returns notifications in response to successful query execution to give the users some advice on how to improve the quality of the query or to provide additional information about the query execution. -From Neo4j 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j codes. -GQLSTATUS codes are returned as part of the result summary and provide diagnostic information about the status of a Cypher query or command execution, including the outcome of the execution (successful completion, warnings, no data, information), the diagnostic code, and the diagnostic message. +From version 5.23, Neo4j supports GQL-status notifications in addition to the existing Neo4j client notifications when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + +GQL-status notifications provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. +It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. -The following sections describe the Neo4j and the GQLSTATUS notification codes. +This page describes both the Neo4j and the GQL-status notification frameworks, how they are structured, their notification objects, and how to interpret them. -[[notification-object]] -== Notification object -The notification object contains diagnostic information representing the status of a Cypher query or command execution, including the outcome of the execution, the diagnostic code, and the diagnostic message. -The notification object is part of the result summary and is returned by the server with severity `WARNING` or `INFORMATION`. +[[neo4j-notification-object]] +== Neo4j notification object -The notification object consists of the following fields: +The Neo4j notification object contains diagnostic information representing the status of a Cypher query or command execution, including the neo4j `ClientNotification` code, title, severity level, category, 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. -[.tabbed-example] -===== -[.include-with-neo4j-code] -====== +The notification object consists of the following fields: +.Neo4j notification object [cols="<1s,<4"] |=== |Neo4j code @@ -40,37 +37,164 @@ a|The category of the notification. |Position a|The position, given by row and column, where the notification is relevant in the query text. |=== -====== -[.include-with-GQLSTATUS-code] -====== + +[role=label--version-5.23] +[[gqlstatus-notification-object]] +== GQL-status notification object + +The Neo4j GQL-status 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 <>. + +Each GQL-status object contains diagnostic information about the execution outcome. +This information includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. + +The main GQL-status object, describing the condition with the greatest precedence, is called the primary GQL-status object. +The primary GQL-status object is always present in the execution outcome and follows the GQL precedence rules: + +. `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. + +The primary 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. +For more information about notification grouping and filtering, see <>. + +The additional GQL-status objects are part of the list of additional GQL-status objects of the execution outcome. +The list does not follow any specific order and might be empty as well. + +The GQL-status object consists of the following fields: + +.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. -|Status description -a| -|Severity level -a|The severity can be one of the following: +|GQLSTATUS description +a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and a description. +The condition and subcondition are the class and subclass codes, respectively. +| Diagnostic record +a| Extra information about the status, given as key-value pairs, both on the server and driver side. +The full diagnostic record can be returned by the `getDiagnosticRecord()` method on the server side and the `diagnosticRecord()` methods on the driver side. +Additional helper methods are exposed for some useful fields. +[cols="<1s,<4"] +!=== +! Field ! Description +! OPERATION ! The operation that the notification is related to. +! OPERATION_CODE ! The operation code that the notification is related to. +! CURRENT_SCHEMA ! The current schema that the notification is related to. +! severity ! The Neo4j severity level, which 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. -|Classification -a|The category of the notification. -|Position -a|The position, given by row and column, where the notification is relevant in the query text. +! classification ! The Neo4j category of the notification. +! position ! The position, given by row and column, where the notification is relevant in the query text. +! status_parameters ! A map that contains all variable parts of the status description. +!=== +|=== + + +[[general-codes-for-success]] +=== General codes for success + +GQL has three general codes for success, indicated by different GQLSTATUS codes in categories S (successful completion) and N (no data), which are not covered by the Neo4j notification framework and are considered to be the default statuses for successful completion, omitted result, and no data, respectively. +The Neo4j classification, severity, position, and status parameters are not meaningful for these GQL statuses, so they are not included in the diagnostic record and are set to default values either by the server or by the driver. + +.GQLSTATUS general codes +[cols="1,2,1,4", options="header"] +|=== +|GQLSTATUS +|Condition +|Subcondition +|Description + +| 00000 +| Successful completion +| +| Successful completion with a regular non-empty result (n > 0 columns, m > 0 rows), for example, a `RETURN` clause with matches. + +| 00001 +| Successful completion +| Omitted result +| Successful completion with no return columns (n = 0 columns, m = 0 rows), for example, link:https://neo4j.com/docs/cypher-manual/current/planning-and-tuning/[`EXPLAIN` queries]. + +| 02000 +| No data +| +| Successful completion with an empty result (n > 0 columns, m = 0 rows), for example, a `MATCH` clause with no matches. |=== -====== -===== -[[notification-categories]] -== Notification code grouping +GQLSTATUS general codes are filled in by the server unless the server is too old to be aware of GQL-status objects, in which case, it is polyfilled by the driver (see <>). +The driver tries to deduce `SUCCESS`, `OMITTED RESULT`, or `NO DATA` from the returned number of records and columns. +If that fails, it uses the GQLSTATUS 02N42 (`no data: unknown subcondition. Unknown GQLSTATUS from old server.`) to indicate that the server did not provide a GQL-status object. +Then, it poly-fills statuses from the notifications and merges the two lists according to the GQL precedence rules described in <>. + +[[gqlstatus-codes]] +=== Neo4j-defined GQLSTATUS codes -All Neo4j notification codes are grouped by category/classification and severity `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. +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 groups exist, ordered by severity: +The following table lists the Neo4j-defined groups of GQLSTATUS codes and their meanings: -.Neo4j notification categories +.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 + +|=== + +[[notification-grouping-and-filtering]] +== Server notification grouping and filtering + +All server notifications are grouped by category (which is called classification in the GQLSTATUS framework) and severity level, which can be one of `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. + +The driver-side notification configuration used for filtering notifications by category and severity is the same for both Neo4j and GQLSTATUS notifications. +The driver can filter notifications by category/classification and severity level, and the server will only send notifications that match the driver-side configuration. + +The driver can also choose to ignore notifications. +However, as per the GQLSTATUS framework, the server must always send the primary GQL-status object. +Therefore, if notifications are off or the notification configuration filtering is set to filter out all notifications, the server will still send the primary GQL-status object with the status `SUCCESSFUL COMPLETION`, `OMITTED RESULT` or `NO DATA`. + +The following notification groups exist in Neo4j, ordered by severity: + +.Notification groups and severity levels [options="header", cols="<1m,<1m,<3,<2"] |=== | CATEGORY/CLASSIFICATION @@ -124,17 +248,28 @@ The following groups exist, ordered by severity: | |=== -[[role=label--version-5.23]] -[[gqlstatus-codes]] -== GQLSTATUS notifications +[[server-driver-compatibility]] +== Server-driver 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]. + +The GqlStatusObject API is available in Neo4j 5.22 and later versions on the server side and in the 5.23 driver and later versions on the driver side. +The current Notification API is still present, and the GqlStatusObject API can be used in parallel with it. + +To receive the Gql-status notifications, both your server and the driver must support the GqlStatusObject API. +Drivers that are older than 5.23 send only notifications from the Notification API, even if the server is 5.22 or later. + +If the 5.23 driver talks to a server that is too old to be aware of GQL-status objects, the driver tries to deduce `SUCCESS`, `OMITTED RESULT`, or `NO DATA` from the returned number of records and columns. +If that fails, it uses the GQLSTATUS 02N42 (`no data: unknown subcondition. Unknown GQLSTATUS from old server.`) to indicate that the server did not provide a GQL-status object. +Then, it poly-fills statuses from the notifications and merges the two lists according to the GQL precedence rules described in <>. + +// The following table illustrates the compatibility between the different server and driver versions for both the current Notification API and the GqlStatusObject API: +// TODO -[[gqlstatus-notification-format]] -== GQL-status object -In full, the execution outcome succeeds or fails, GQL mandates that it contains an object, called a GQL-status object, representing the diagnostic information. The GQL-status object can be also accompanied with a list of other additional GQL-status objects describing additional diagnostic information related to the execution of the same GQL-request. The list is empty by default, unless the implementation chooses to make the additional GQL-status objects available. The main GQL-status object is called the primary GQL-status object. -are the GQLSTATUS code and the status description. -The notification object, which is part of the result summary, consists of the following fields: From f7d243c9560549d93d95b1bb502734b449987c03 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 14:04:44 +0100 Subject: [PATCH 03/12] Update modules/ROOT/pages/changelogs.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/changelogs.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/changelogs.adoc b/modules/ROOT/pages/changelogs.adoc index f4a07560..d3fc1b02 100644 --- a/modules/ROOT/pages/changelogs.adoc +++ b/modules/ROOT/pages/changelogs.adoc @@ -4,7 +4,7 @@ == Neo4j 5.23 From version 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j `ClientNotification` codes when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + -GQLSTATUS codes provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. +The GqlStatusObject API provides diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. For more information, see xref:notifications/index.adoc[Server notifications] and xref:notifications/all-notifications.adoc[List of all server notification codes]. From 091832f6a11661551bb7dd9ad43cdb00e2b18853 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 14:06:04 +0100 Subject: [PATCH 04/12] Update modules/ROOT/pages/notifications/index.adoc Co-authored-by: Louise Berglund --- 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 12724f36..6471a0b7 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -9,7 +9,7 @@ From version 5.23, Neo4j supports GQL-status notifications in addition to the ex GQL-status notifications provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. -This page describes both the Neo4j and the GQL-status notification frameworks, how they are structured, their notification objects, and how to interpret them. +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. [[neo4j-notification-object]] From 00874da8b31e1a8e560a5b98aea76eb06d23b2a7 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 14:07:47 +0100 Subject: [PATCH 05/12] Update modules/ROOT/pages/notifications/index.adoc Co-authored-by: Louise Berglund --- 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 6471a0b7..b2a7f3bb 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -43,7 +43,7 @@ a|The position, given by row and column, where the notification is relevant in t [[gqlstatus-notification-object]] == GQL-status notification object -The Neo4j GQL-status 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`. +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 <>. Each GQL-status object contains diagnostic information about the execution outcome. From 1c7bbe3c91419a9ea9bcb6b8801d921d4f8b7942 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 14:08:47 +0100 Subject: [PATCH 06/12] Update modules/ROOT/pages/notifications/index.adoc Co-authored-by: Louise Berglund --- 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 b2a7f3bb..1d179ae1 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -183,7 +183,7 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their [[notification-grouping-and-filtering]] == Server notification grouping and filtering -All server notifications are grouped by category (which is called classification in the GQLSTATUS framework) and severity level, which can be one of `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. +All server notifications are grouped by category (which is called classification in the GqlStatusObject framework) and severity level, which can be one of `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. The driver-side notification configuration used for filtering notifications by category and severity is the same for both Neo4j and GQLSTATUS notifications. The driver can filter notifications by category/classification and severity level, and the server will only send notifications that match the driver-side configuration. From 174d60e3b7162c5b8b1032ad331dd87067a17168 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 18:57:10 +0200 Subject: [PATCH 07/12] rework the page after PR review --- modules/ROOT/pages/changelogs.adoc | 9 +-- modules/ROOT/pages/index.adoc | 9 +-- modules/ROOT/pages/notifications/index.adoc | 79 ++++++++++++--------- 3 files changed, 57 insertions(+), 40 deletions(-) diff --git a/modules/ROOT/pages/changelogs.adoc b/modules/ROOT/pages/changelogs.adoc index d3fc1b02..6e134a68 100644 --- a/modules/ROOT/pages/changelogs.adoc +++ b/modules/ROOT/pages/changelogs.adoc @@ -3,10 +3,11 @@ == Neo4j 5.23 -From version 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j `ClientNotification` codes when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + -The GqlStatusObject API provides diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. -It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. -For more information, see xref:notifications/index.adoc[Server notifications] and xref:notifications/all-notifications.adoc[List of all server notification codes]. +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]. == Neo4j 5.17 diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 02c519e1..48b7d109 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -57,10 +57,11 @@ The type of the status code determines the effect on the transaction. [NOTE] ==== -From version 5.23, Neo4j supports GQLSTATUS codes in addition to the existing Neo4j `ClientNotification` codes when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + -GQLSTATUS codes provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. -It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. -For more information, see xref:notifications/index.adoc[Server notifications]. +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]. ==== ifndef::backend-pdf[] diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 1d179ae1..d53015bf 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -3,19 +3,16 @@ [[notifications]] = Server notifications -The Neo4j server returns notifications in response to successful query execution to give the users some advice on how to improve the quality of the query or to provide additional information about the query execution. - -From version 5.23, Neo4j supports GQL-status notifications in addition to the existing Neo4j client notifications when used with the latest drivers and configured to use both the Neo4j and GQLSTATUS framework. + -GQL-status notifications provide diagnostic information about the status of a Cypher query or command execution in compliance with the GQL standard. -It includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. - -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. +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 GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard. [[neo4j-notification-object]] == Neo4j notification object -The Neo4j notification object contains diagnostic information representing the status of a Cypher query or command execution, including the neo4j `ClientNotification` code, title, severity level, category, 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 notification object consists of the following fields: @@ -26,6 +23,8 @@ The notification object consists of the following fields: |Neo4j code a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. |Title +a|The title of the notification. +|Description a|The description of the Neo4j status code. |Severity level a|The severity can be one of the following: @@ -44,51 +43,49 @@ a|The position, given by row and column, where the notification is relevant in t == 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 <>. +For the latter, see <>. + -Each GQL-status object contains diagnostic information about the execution outcome. -This information includes the GQLSTATUS code, the execution outcome (successful completion, warnings, no data, information), the status description, and the diagnostic record. + -The main GQL-status object, describing the condition with the greatest precedence, is called the primary GQL-status object. -The primary GQL-status object is always present in the execution outcome and follows the GQL precedence rules: +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: . `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. -The primary 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. -For more information about notification grouping and filtering, see <>. +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 additional GQL-status objects are part of the list of additional GQL-status objects of the execution outcome. -The list does not follow any specific order and might be empty as well. +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. +For more information about notification grouping and filtering, see <>. -The GQL-status object consists of the following fields: +Each GQL-status object consists of the following fields: .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. -|GQLSTATUS description +|StatusDescription a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and a description. -The condition and subcondition are the class and subclass codes, respectively. -| Diagnostic record +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. The full diagnostic record can be returned by the `getDiagnosticRecord()` method on the server side and the `diagnosticRecord()` methods on the driver side. Additional helper methods are exposed for some useful fields. [cols="<1s,<4"] !=== ! Field ! Description -! OPERATION ! The operation that the notification is related to. -! OPERATION_CODE ! The operation code that the notification is related to. -! CURRENT_SCHEMA ! The current schema that the notification is related to. -! severity ! The Neo4j severity level, which can be one of the following: +! `OPERATION` ! The operation that the notification is related to. Always defaults to empty. +! `OPERATION_CODE` ! The operation code that the notification is related to. Always defaults to `0`. +! `CURRENT_SCHEMA` ! The current schema that the notification is related to. Always defaults to `/`. +! `_severity` ! The Neo4j severity level, which 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. -! classification ! The Neo4j category of the notification. -! position ! The position, given by row and column, where the notification is relevant in the query text. -! status_parameters ! A map that contains all variable parts of the status description. +!`_classification` ! The Neo4j category of the notification. +! `_position` ! The position, given by row and column, where the notification is relevant in the query text. +! `_status_parameters`! A map that contains all variable parts of the status description. !=== |=== @@ -185,7 +182,7 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their All server notifications are grouped by category (which is called classification in the GqlStatusObject framework) and severity level, which can be one of `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. -The driver-side notification configuration used for filtering notifications by category and severity is the same for both Neo4j and GQLSTATUS notifications. +The driver-side notification configuration used for filtering notifications by category and severity is the same for both Neo4j and GQLSTATUS notification frameworks. The driver can filter notifications by category/classification and severity level, and the server will only send notifications that match the driver-side configuration. The driver can also choose to ignore notifications. @@ -248,17 +245,35 @@ The following notification groups exist in Neo4j, ordered by severity: | |=== -[[server-driver-compatibility]] -== Server-driver compatibility +[[server-driver-communication]] +== Server-driver communication 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]. +On the server side, notifications are part of the Result Core API. +A method called `getNotifications()` 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. +Driver-side notification configuration filters notifications by severity and/or category at both the driver and session levels. +For more information, see <>. + +From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API. +This can be used using the `.getGqlStatusObjects()` method in the Result Core API or by using the latest Neo4j drivers. + +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 (which contains the status of the execution - successful completion, warnings, no data, or information, and a message), and DiagnosticRecord. + +This page describes both the Neo4j Notification and the GQL-status object frameworks, how they are structured, the objects they provide for notifications, how to interpret them, and the server and driver compatibility for both frameworks. + +[[server-driver-compatibility]] +== Server-driver compatibility + The GqlStatusObject API is available in Neo4j 5.22 and later versions on the server side and in the 5.23 driver and later versions on the driver side. The current Notification API is still present, and the GqlStatusObject API can be used in parallel with it. -To receive the Gql-status notifications, both your server and the driver must support the GqlStatusObject API. +To fully utilize the GqlStatusObject API, both your server and the driver must support it. Drivers that are older than 5.23 send only notifications from the Notification API, even if the server is 5.22 or later. If the 5.23 driver talks to a server that is too old to be aware of GQL-status objects, the driver tries to deduce `SUCCESS`, `OMITTED RESULT`, or `NO DATA` from the returned number of records and columns. From 4655e814af900eee004af9c2ebc41bcea130fbc9 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 16 Aug 2024 19:20:12 +0200 Subject: [PATCH 08/12] further edits --- modules/ROOT/pages/notifications/index.adoc | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index d53015bf..22ce2d9e 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -9,6 +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. +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 @@ -245,8 +248,8 @@ The following notification groups exist in Neo4j, ordered by severity: | |=== -[[server-driver-communication]] -== Server-driver communication +[[notification-internals]] +== Notification 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. @@ -261,14 +264,10 @@ Driver-side notification configuration filters notifications by severity and/or For more information, see <>. From version 5.23, Neo4j has a new GqlStatusObject API in addition to the existing Notification API. -This can be used using the `.getGqlStatusObjects()` method in the Result Core API or by using the latest Neo4j drivers. + -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 (which contains the status of the execution - successful completion, warnings, no data, or information, and a message), and DiagnosticRecord. - -This page describes both the Neo4j Notification and the GQL-status object frameworks, how they are structured, the objects they provide for notifications, how to interpret them, and the server and driver compatibility for both frameworks. +This can be used using the `.getGqlStatusObjects()` method in the Result Core API or by using the latest Neo4j drivers. [[server-driver-compatibility]] -== Server-driver compatibility +== Server-driver version compatibility The GqlStatusObject API is available in Neo4j 5.22 and later versions on the server side and in the 5.23 driver and later versions on the driver side. The current Notification API is still present, and the GqlStatusObject API can be used in parallel with it. From 2c3c51ca08fb5842fb889efc0caf1935b4c2d4e5 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 20 Aug 2024 10:04:20 +0200 Subject: [PATCH 09/12] Update modules/ROOT/pages/notifications/index.adoc --- 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 22ce2d9e..c115fe0e 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -74,7 +74,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. -The full diagnostic record can be returned by the `getDiagnosticRecord()` method on the server side and the `diagnosticRecord()` methods on the 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"] !=== From 327bb0eb00d497cc91d5fe3141791a99ec633e8d Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 20 Aug 2024 10:05:22 +0200 Subject: [PATCH 10/12] Apply suggestions from code review Co-authored-by: Louise Berglund --- 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 c115fe0e..5f1b405f 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -185,7 +185,7 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their All server notifications are grouped by category (which is called classification in the GqlStatusObject framework) and severity level, which can be one of `WARNING`, `WARNING OR INFORMATION`, or `INFORMATION`. -The driver-side notification configuration used for filtering notifications by category and severity is the same for both Neo4j and GQLSTATUS notification frameworks. +The driver-side notification configuration used for filtering notifications by category and severity is the same for both Neo4j Notification and GQL-status object frameworks. The driver can filter notifications by category/classification and severity level, and the server will only send notifications that match the driver-side configuration. The driver can also choose to ignore notifications. From 5f27fe633b48c7a162c3aa78cc7c6dc24fc144f5 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 20 Aug 2024 10:54:59 +0200 Subject: [PATCH 11/12] Update modules/ROOT/pages/notifications/index.adoc Co-authored-by: Louise Berglund --- modules/ROOT/pages/notifications/index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 5f1b405f..31086ae4 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -26,9 +26,9 @@ The notification object consists of the following fields: |Neo4j code a|The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`. |Title -a|The title of the notification. +a|The title of the Neo4j status code. |Description -a|The description of the Neo4j status code. +a|The description of the specific notification. |Severity level a|The severity can be one of the following: From e7b16dc3e713a54fedf1fb3e325ade9cfa720900 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:20:37 +0200 Subject: [PATCH 12/12] Fix small asciidoc mistake --- modules/ROOT/pages/notifications/index.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index 31086ae4..f00db72c 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -82,10 +82,11 @@ Additional helper methods are exposed for some useful fields. ! `OPERATION` ! The operation that the notification is related to. Always defaults to empty. ! `OPERATION_CODE` ! The operation code that the notification is related to. Always defaults to `0`. ! `CURRENT_SCHEMA` ! The current schema that the notification is related to. Always defaults to `/`. -! `_severity` ! The Neo4j severity level, which can be one of the following: +! `_severity` a! The Neo4j severity level, which 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. + !`_classification` ! The Neo4j category of the notification. ! `_position` ! The position, given by row and column, where the notification is relevant in the query text. ! `_status_parameters`! A map that contains all variable parts of the status description.