This PR introduces GQL compliant status objects to the ResultSummary.
:warning: This feature is still in PREVIEW.
It might be changed without following the deprecation policy.
Deprecations
SummaryNotificationPosition has been deprecated in favor of SummaryInputPosition.
New GQL Status Objects
A new property ResultSummary.gql_status_objects has been introduced. It returns a sequence of GqlStatusObjects. These objects contain information about the execution of the query including notifications as they exist now (see SummaryNotification) but also an outcome status like 00000 for "success", 02000 for "no data", and 00001 for "omitted result".
Eventually, this API is planned to supersede the current notifications API.
The GqlStatusObjects will be presented in the following order:
A "no data" (02xxx) has precedence over a warning;
A "warning" (01xxx) has precedence over a success.
A "success" (00xxx) has precedence over anything informational (03xxx).
Notification Filtering
Some status objects are notifications (vendor-specific definition). Those notifications can be identified using GqlStatusObject.is_notification. They contain additional information like a classification, severity, and position. Further, those notifications can be configured to be suppressed in the DBMS saving bandwidth not having to send them to the client as well as compute not having to check for those conditions.
For this, the following driver config options can be used:
notifications_min_severity (already existing)
notifications_disabled_classifications (new, same as the existing notifications_disabled_categories).
If both options are provided, they are merged into a single list of disabled classifications/categories.
All filter config options will affect both the current notifications API as well as the notifications among the GQL status objects.
Polyfilling
There are now two APIs to access notifications: the old notifications API and the new GQL status API. To provide an easy migration path the driver will, depending on if the server is GQL aware or not (i.e., recent or old neo4j version), polyfill the API not supported by the server on a best-effort basis. In particular, GQL status objects have a GQLSTATUS code that has not counterpart in non-GQL-aware neo4j versions. Therefore, the driver will fill the GQLSTATUS with either 01N42 for warning notifications and 03N42 for informational notifications. Further, such status codes might be used by the server in the transition phase towards full GQL compliance. They indicate a lack of a final status code and will likely change in the future.
A list of all possible GQLSTATUS codes is not yet available as the server-side of this change is still very actively being worked on.
Example Usage
with neo4j.GraphDatabase.driver(
URI,
auth=AUTH,
notifications_disabled_classifications=[
# Remove this filter entry to get an additional notification
# about the usage of a cartesian product.
neo4j.NotificationClassification.PERFORMANCE
],
) as driver:
_, summary, _ = driver.execute_query(
"MATCH (n:Foo), (m) RETURN n.nope, m"
)
assert isinstance(summary, neo4j.ResultSummary)
for status in summary.gql_status_objects:
# The GQLSTATUS code of the status object.
print("GQLSTATUS:", status.gql_status)
# A description of the status for human consumption.
print("description:", status.status_description)
# Whether the status is a notification and can be filtered.
print("is notification:", status.is_notification)
# Notification and thus vendor-specific fields.
# These fields are only meaningful for notifications.
if status.is_notification:
# The position in the query that caused the notification.
print("position:", status.position)
# The notification's classification.
# This is the counterpart to `neo4j.NotificationCategory`,
# however, the term category is already used for a different
# context in the context of GQL
print("classification:", status.classification)
print("unparsed classification:", status.raw_classification)
# The notification's severity.
print("severity:", status.severity)
print("unparsed severity:", status.raw_severity)
# Any raw extra information provided by the DBMS:
print("diagnostic record:", status.diagnostic_record)
print("=" * 80)
Which, when run against an empty 5.19 DBMS, gives the following output
GQLSTATUS: 02000
description: note: no data
is notification: False
diagnostic record: {'OPERATION': '', 'OPERATION_CODE': '0', 'CURRENT_SCHEMA': '/'}
================================================================================
GQLSTATUS: 01N42
description: One of the labels in your query is not available in the database, make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing label name is: Foo)
is notification: True
position: line: 1, column: 10, offset: 9
classification: NotificationClassification.UNRECOGNIZED
unparsed classification: UNRECOGNIZED
severity: NotificationSeverity.WARNING
unparsed severity: WARNING
diagnostic record: {'OPERATION': '', 'OPERATION_CODE': '0', 'CURRENT_SCHEMA': '/', '_classification': 'UNRECOGNIZED', '_severity': 'WARNING', '_position': {'column': 10, 'offset': 9, 'line': 1}}
================================================================================
GQLSTATUS: 01N42
description: One of the property names in your query is not available in the database, make sure you didn't misspell it or that the label is available when you run this statement in your application (the missing property name is: nope)
is notification: True
position: line: 1, column: 29, offset: 28
classification: NotificationClassification.UNRECOGNIZED
unparsed classification: UNRECOGNIZED
severity: NotificationSeverity.WARNING
unparsed severity: WARNING
diagnostic record: {'OPERATION': '', 'OPERATION_CODE': '0', 'CURRENT_SCHEMA': '/', '_classification': 'UNRECOGNIZED', '_severity': 'WARNING', '_position': {'column': 29, 'offset': 28, 'line': 1}}
================================================================================
GQL Summary Statuses
This PR introduces GQL compliant status objects to the
ResultSummary
.:warning: This feature is still in PREVIEW. It might be changed without following the deprecation policy.
Deprecations
SummaryNotificationPosition
has been deprecated in favor ofSummaryInputPosition
.New GQL Status Objects
A new property
ResultSummary.gql_status_objects
has been introduced. It returns a sequence ofGqlStatusObject
s. These objects contain information about the execution of the query including notifications as they exist now (seeSummaryNotification
) but also an outcome status like00000
for "success",02000
for "no data", and00001
for "omitted result".Eventually, this API is planned to supersede the current notifications API.
The GqlStatusObjects will be presented in the following order:
02xxx
) has precedence over a warning;01xxx
) has precedence over a success.00xxx
) has precedence over anything informational (03xxx
).Notification Filtering
Some status objects are notifications (vendor-specific definition). Those notifications can be identified using
GqlStatusObject.is_notification
. They contain additional information like aclassification
,severity
, andposition
. Further, those notifications can be configured to be suppressed in the DBMS saving bandwidth not having to send them to the client as well as compute not having to check for those conditions.For this, the following driver config options can be used:
notifications_min_severity
(already existing)notifications_disabled_classifications
(new, same as the existingnotifications_disabled_categories
). If both options are provided, they are merged into a single list of disabled classifications/categories.All filter config options will affect both the current notifications API as well as the notifications among the GQL status objects.
Polyfilling
There are now two APIs to access notifications: the old notifications API and the new GQL status API. To provide an easy migration path the driver will, depending on if the server is GQL aware or not (i.e., recent or old neo4j version), polyfill the API not supported by the server on a best-effort basis. In particular, GQL status objects have a GQLSTATUS code that has not counterpart in non-GQL-aware neo4j versions. Therefore, the driver will fill the GQLSTATUS with either
01N42
for warning notifications and03N42
for informational notifications. Further, such status codes might be used by the server in the transition phase towards full GQL compliance. They indicate a lack of a final status code and will likely change in the future.A list of all possible GQLSTATUS codes is not yet available as the server-side of this change is still very actively being worked on.
Example Usage
Which, when run against an empty 5.19 DBMS, gives the following output
Depends on: