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.

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

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:

Table 1. Neo4j notification object
Neo4j code	The Neo4j status code in the form of `Neo.ClientNotification.[SubType].[Name]`.
Title	The title of the Neo4j status code.
Description	The description of the specific notification.
Severity level	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.

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 General codes for success.

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 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. For more information about notification grouping and filtering, see Server notification grouping and filtering.

Each GQL-status object consists of the following fields:

GQLSTATUS code

A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code.

StatusDescription

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

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.

Field

Description

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.

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.

Table 3. GQLSTATUS general codes
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, `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.

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 Server - driver compatibility).

Neo4j-defined GQLSTATUS 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:

Table 4. GQLSTATUS groups of codes as defined by Neo4j
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

Server notification grouping and filtering

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 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. 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:

Table 5. Notification groups and severity levels
CATEGORY/CLASSIFICATION	SEVERITY	EXPLANATION	RECOMMENDED ACTION
`DEPRECATION`	`WARNING`	The query or command uses deprecated features that should be replaced.	Update to use the new functionality.
`HINT`	`WARNING`	The given hint cannot be satisfied.	Remove the hint or fix the query so the hint can be used.
`UNSUPPORTED`	`WARNING`	The query or command is trying to use features not supported by the current system or using experimental features that should not be used in production.	Unsupported features cannot be trusted and should not be used in production.
`UNRECOGNIZED`	`WARNING OR INFORMATION`	The query or command mentions entities that are unknown to the system.	Make sure you have not misspelled the entity.
`SECURITY`	`WARNING OR INFORMATION`	The result of the query or command indicates a potential security issue.	Make sure that the behaviour is what you intended.
`TOPOLOGY`	`INFORMATION`	Information provided while executing database and server related commands.
`SCHEMA`	`INFORMATION`	Information provided while managing indexes and constraints.
`GENERIC`	`WARNING OR INFORMATION`	Notifications that are not part of a wider class.	Depends on the specific notification.
`PERFORMANCE`	`INFORMATION`	The query uses costly operations and might be slow. Consider if it is possible to rewrite the query in a different way.

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. For more information on the Bolt versions supported by different server versions, see the 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 Server notification grouping and filtering.

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.

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.

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 a driver of version 5.23 or later talks to a server that is too old to be aware of GQL-status objects, the driver needs to poly-fill the GqlStatusObject API with information. The driver tries to deduce SUCCESS, OMITTED RESULT, or NO DATA from the returned number of records and columns. If that fails, the general GQLSTATUS code will be set to 02N42. Then, the driver poly-fills the rest of the GQL-status object list with the notifications from the old notification API. These will get GQLSTATUS 01N42 for notifications with severity WARNING and 03N42 for notifications with severity INFORMATION. Finally, the list of poly-filled GQL-status objects is sorted according to the GQL precedence rules described in GQL-status notification object.

Table 6. GQLSTATUS compatibility codes
GQLSTATUS	Condition	Subcondition	Description
01N42	Warning	Unknown warning	Poly-filled notification with severity `WARNING`.
02N42	No data	Unknown subcondition	Poly-filled general status when `SUCCESS`, `OMITTED RESULT`, or `NO DATA` cannot be deduced.
03N42	Informational	Unknown notification	Poly-filled notification with severity `INFORMATION`.