# GQL Summary Statuses

This PR introduces GQL compliant status objects to the `ResultSummary`.

⚠️ 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 `GqlStatusObject`s. 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
```python
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}}
================================================================================
```

Author: robsdedude

CHANGELOG.md

@@ -3,7 +3,7 @@
 See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
 
 ## NEXT RELEASE
-- No breaking or major changes.
+- `SummaryNotificationPosition` has been deprecated in favor of `SummaryInputPosition`.
 
 
 ## Version 5.17 - 5.21

docs/source/api.rst

@@ -686,6 +686,9 @@ Set the minimum severity for notifications the server should send to the client.
 Disabling severities allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced through :attr:`.ResultSummary.gql_status_objects`:
+For GQL-aware servers, notifications are a subset of GqlStatusObjects.
+See also :attr:`.GqlSatusObject.is_notification`.
 
 :data:`None` will apply the server's default setting.
 
@@ -706,13 +709,17 @@ Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`
 
 ``notifications_disabled_categories``
 -------------------------------------
-Set categories of notifications the server should not send to the client.
+Set categories/classifications of notifications the server should not send to the client.
 Disabling categories allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced (alongside other status objects) through :attr:`.ResultSummary.gql_status_objects`:
+See also :attr:`.GqlSatusObject.is_notification`.
 
 :data:`None` will apply the server's default setting.
 
+If specified together with :ref:`driver-notifications-disabled-classifications-ref`, the settings will be merged.
+
 .. Note::
     If configured, the server or all servers of the cluster need to support notifications filtering
     (server version 5.7 and newer).
@@ -726,6 +733,27 @@ Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`
 .. seealso:: :class:`.NotificationDisabledCategory`, session config :ref:`session-notifications-disabled-categories-ref`
 
 
+.. _driver-notifications-disabled-classifications-ref:
+
+``notifications_disabled_classifications``
+------------------------------------------
+Identical to :ref:`driver-notifications-disabled-categories-ref`.
+
+This alias is provided for a consistent naming with :attr:`.GqlStatusObject.classification`.
+
+**This is a preview** (see :ref:`filter-warnings-ref`).
+It might be changed without following the deprecation policy.
+See also
+https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
+:Type: :data:`None`, :term:`iterable` of :class:`.NotificationDisabledClassification` and/or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.22
+
+.. seealso:: :class:`.NotificationDisabledClassification`, session config :ref:`session-notifications-disabled-classifications-ref`
+
+
 .. _driver-warn-notification-severity-ref:
 
 ``warn_notification_severity``
@@ -1159,11 +1187,14 @@ Set the minimum severity for notifications the server should send to the client.
 Disabling severities allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced (alongside other status objects) through :attr:`.ResultSummary.gql_status_objects`:
+See also :attr:`.GqlSatusObject.is_notification`.
 
 :data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-min-severity-ref`).
 
 .. Note::
-    If configured, the server or all servers of the cluster need to support notifications filtering.
+    If configured, the server or all servers of the cluster need to support notifications filtering
+    (server version 5.7 and newer).
     Otherwise, the driver will raise a :exc:`.ConfigurationError` as soon as it encounters a server that does not.
 
 :Type: :data:`None`, :class:`.NotificationMinimumSeverity`, or :class:`str`
@@ -1182,11 +1213,16 @@ Set categories of notifications the server should not send to the client.
 Disabling categories allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced (alongside other status objects) through :attr:`.ResultSummary.gql_status_objects`:
+See also :attr:`.GqlSatusObject.is_notification`.
 
-:data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-min-severity-ref`).
+:data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-disabled-categories-ref`).
+
+If specified together with :ref:`session-notifications-disabled-classifications-ref`, the settings will be merged.
 
 .. Note::
-    If configured, the server or all servers of the cluster need to support notifications filtering.
+    If configured, the server or all servers of the cluster need to support notifications filtering
+    (server version 5.7 and newer).
     Otherwise, the driver will raise a :exc:`.ConfigurationError` as soon as it encounters a server that does not.
 
 :Type: :data:`None`, :term:`iterable` of :class:`.NotificationDisabledCategory` and/or :class:`str`
@@ -1197,6 +1233,27 @@ Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`
 .. seealso:: :class:`.NotificationDisabledCategory`
 
 
+.. _session-notifications-disabled-classifications-ref:
+
+``notifications_disabled_classifications``
+------------------------------------------
+Identical to :ref:`session-notifications-disabled-categories-ref`.
+
+This alias is provided for a consistent naming with :attr:`.GqlStatusObject.classification`.
+
+**This is a preview** (see :ref:`filter-warnings-ref`).
+It might be changed without following the deprecation policy.
+See also
+https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
+:Type: :data:`None`, :term:`iterable` of :class:`.NotificationDisabledClassification` and/or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.22
+
+.. seealso:: :class:`.NotificationDisabledClassification`
+
+
 
 ***********
 Transaction
@@ -1521,6 +1578,20 @@ ServerInfo
    :members:
 
 
+GqlStatusObject
+===============
+
+.. autoclass:: neo4j.GqlStatusObject()
+    :members:
+
+
+NotificationClassification
+--------------------------
+
+.. autoclass:: neo4j.NotificationClassification()
+    :members:
+
+
 SummaryNotification
 ===================
 
@@ -1542,11 +1613,26 @@ NotificationCategory
     :members:
 
 
+SummaryInputPosition
+--------------------
+
+.. autoclass:: neo4j.SummaryInputPosition()
+    :members:
+
+
 SummaryNotificationPosition
 ---------------------------
 
-.. autoclass:: neo4j.SummaryNotificationPosition()
-    :members:
+.. data:: neo4j.SummaryNotificationPosition
+    :annotation: = neo4j.SummaryInputPosition
+
+    Deprecated alias for :class:`.SummaryInputPosition`.
+
+    .. versionadded:: 5.7
+
+    .. versionchanged:: 5.22
+        Deprecated in favor of :class:`.SummaryInputPosition`.
+
 
 
 
@@ -1869,6 +1955,9 @@ Constants, Enums, Helpers
     :show-inheritance:
     :members:
 
+.. autoclass:: neo4j.NotificationDisabledClassification()
+    :members:
+
 .. autoclass:: neo4j.RoutingControl()
     :show-inheritance:
     :members:

src/neo4j/__init__.py

@@ -14,11 +14,13 @@
 # limitations under the License.
 
 
+import typing as _t
 from logging import getLogger as _getLogger
 
 from ._api import (
     NotificationCategory,
     NotificationDisabledCategory,
+    NotificationDisabledClassification as _NotificationDisabledClassification,
     NotificationMinimumSeverity,
     NotificationSeverity,
     RoutingControl,
@@ -49,6 +51,7 @@
     deprecation_warn as _deprecation_warn,
     ExperimentalWarning,
     get_user_agent,
+    preview_warn as _preview_warn,
     PreviewWarning,
     version as __version__,
 )
@@ -67,13 +70,25 @@
 )
 from ._work import (
     EagerResult,
+    GqlStatusObject as _GqlStatusObject,
+    NotificationClassification as _NotificationClassification,
     Query,
     ResultSummary,
     SummaryCounters,
+    SummaryInputPosition,
     SummaryNotification,
-    SummaryNotificationPosition,
     unit_of_work,
 )
+
+
+if _t.TYPE_CHECKING:
+    from ._api import NotificationDisabledClassification
+    from ._work import (
+        GqlStatusObject,
+        NotificationClassification,
+        SummaryInputPosition as SummaryNotificationPosition
+    )
+
 from .addressing import (
     Address,
     IPv4Address,
@@ -122,20 +137,23 @@
     "Config",
     "custom_auth",
     "DEFAULT_DATABASE",
-    "NotificationDisabledCategory",
     "Driver",
     "EagerResult",
     "ExperimentalWarning",
     "get_user_agent",
+    "GqlStatusObject",
     "GraphDatabase",
     "IPv4Address",
     "IPv6Address",
     "kerberos_auth",
     "log",
     "ManagedTransaction",
-    "NotificationMinimumSeverity",
     "Neo4jDriver",
     "NotificationCategory",
+    "NotificationClassification",
+    "NotificationDisabledCategory",
+    "NotificationDisabledClassification",
+    "NotificationMinimumSeverity",
     "NotificationSeverity",
     "PoolConfig",
     "PreviewWarning",
@@ -149,6 +167,7 @@
     "Session",
     "SessionConfig",
     "SummaryCounters",
+    "SummaryInputPosition",
     "SummaryNotification",
     "SummaryNotificationPosition",
     "Transaction",
@@ -173,12 +192,30 @@ def __getattr__(name):
         "log", "Config", "PoolConfig", "SessionConfig", "WorkspaceConfig"
     ):
         _deprecation_warn(
-            "Importing {} from neo4j is deprecated without replacement. It's "
-            "internal and will be removed in a future version."
+            "Importing {} from neo4j is deprecated without replacement. "
+            "It's internal and will be removed in a future version."
             .format(name),
             stack_level=2
         )
         return globals()[f"_{name}"]
+    if name == "SummaryNotificationPosition":
+        _deprecation_warn(
+            "SummaryNotificationPosition is deprecated. "
+            "Use SummaryInputPosition instead.",
+            stack_level=2
+        )
+        return SummaryInputPosition
+    if name in (
+        "NotificationClassification",
+        "GqlStatusObject",
+        "NotificationDisabledClassification",
+    ):
+        _preview_warn(
+            f"{name} is part of GQLSTATUS support, "
+            "which is a preview feature.",
+            stack_level=2
+        )
+        return globals()[f"_{name}"]
     raise AttributeError(f"module {__name__} has no attribute {name}")