服务器通知

在成功执行查询后，Neo4j 服务器会发送通知以提供有关如何提高查询质量或提供有关查询执行的其他信息的建议。驱动程序接收这些通知并将其发送到客户端，客户端将其显示给用户。

从版本 5.23 开始，Neo4j 除了现有的 Notification API 之外，还提供了一个新的 GqlStatusObject API。GqlStatusObject API 提供有关 Cypher 查询或命令执行状态的信息，符合 GQL 标准。

本页面描述了 Neo4j Notification 和 GQL 状态对象框架，它们的结构、它们为通知提供的对象以及如何解释它们。它还解释了服务器通知的分组和过滤、通知内部结构以及 Notification 和 GqlStatusObject API 的服务器-驱动程序兼容性。

Neo4j 通知对象

Neo4j 通知对象包含表示 Cypher 查询或命令执行成功结果的诊断信息，包括严重性、ClientNotification 代码、类别、标题、描述以及查询文本中与通知相关的的位置。根据应用程序的不同，通知对象中的一些字段可能不可见。

通知对象包含以下字段

表 1. Neo4j 通知对象
Neo4j 代码	Neo4j 状态代码，格式为 `Neo.ClientNotification.[SubType].[Name]`。
标题	Neo4j 状态代码的标题。
描述	特定通知的描述。
严重性级别	严重性可以是以下之一 `WARNING`：您的查询可能存在问题。请查看。 `INFORMATION`：查询正确，但此信息仍然有用。
类别	通知的类别。
位置	在查询文本中与通知相关的行和列位置。

GQL 状态通知对象

在 GQL 状态对象框架中，通知是 GQL 状态对象的实现定义的子集，涵盖信息性注释和警告，但不包括错误、SUCCESS、NO DATA 或 OMITTED RESULT。对于后者，请参见成功的一般代码。

在 GQL 中，从用户到服务器的查询执行始终具有结果，称为执行结果。执行结果是 GQL 状态对象的列表，按以下优先级排序，其中列表中的第一个对象是主要 GQL 状态对象

NO DATA 优先于 WARNING。
WARNING 优先于 SUCCESSFUL COMPLETION 子类。
SUCCESSFUL COMPLETION 子类优先于 INFORMATIONAL。
INFORMATIONAL 优先级最低。

主要 GQL 状态对象描述优先级最高的条件，并且始终存在。列表中的所有其他 GQL 状态对象都是附加的 GQL 状态对象。

GQL 状态对象还包含 Neo4j 特定的信息，例如严重性级别和通知的分类，可用于过滤。有关通知分组和过滤的更多信息，请参见服务器通知分组和过滤。

每个 GQL 状态对象包含以下字段

GQLSTATUS 代码

一个 5 个字符的字符串，它是 2 个字符的类代码与 3 个字符的子类代码的连接。

StatusDescription

GQLSTATUS 的人类可读描述，包括条件、子条件和描述。条件和子条件分别是类和子类代码的文本表示。

DiagnosticRecord

有关状态的额外信息，以键值对的形式给出，在服务器端和驱动程序端均可。要检索完整的诊断记录，您可以在服务器端和驱动程序端使用 diagnosticRecord() 方法。针对某些有用字段公开了其他辅助方法。

字段

描述

OPERATION

通知相关的操作。始终默认为空。

OPERATION_CODE

通知相关的操作代码。始终默认为 0。

CURRENT_SCHEMA

通知相关的当前模式。始终默认为 /。

_severity

Neo4j 严重性级别，可以是以下之一

WARNING：您的查询可能存在问题。请查看。
INFORMATION：查询正确，但此信息仍然有用。

_classification

通知的 Neo4j 类别。

_position

在查询文本中与通知相关的行和列位置。

_status_parameters

包含状态描述所有可变部分的映射。

成功的一般代码

GQL 有三种成功的一般代码，由类别 S（成功完成）和 N（无数据）中不同的 GQLSTATUS 代码指示，这些代码不受 Neo4j 通知框架的涵盖，分别被视为成功完成、省略结果和无数据的默认状态。对于这些 GQL 状态，Neo4j 分类、严重性、位置和状态参数没有意义，因此它们不包含在诊断记录中，并由服务器或驱动程序设置为默认值。

表 3. GQLSTATUS 一般代码
GQLSTATUS	条件	子条件	描述
00000	成功完成		使用常规非空结果成功完成（n > 0 列，m > 0 行），例如，带有匹配项的 `RETURN` 子句。
00001	成功完成	省略结果	成功完成但没有返回列（n = 0 列，m = 0 行），例如，`EXPLAIN` 查询。
02000	无数据		成功完成但结果为空（n > 0 列，m = 0 行），例如，没有匹配项的 `MATCH` 子句。

除非服务器过旧以至于不知道 GQL 状态对象，否则服务器会填充 GQLSTATUS 一般代码，在这种情况下，驱动程序会对其进行填充（请参见服务器-驱动程序兼容性）。

Neo4j 定义的 GQLSTATUS 代码

Neo4j 定义的 GQLSTATUS 代码分为类和子类，其中类代码是 2 个字符的字符串（00、01 或 03 中的一个），子类代码是 3 个字符的字符串。类代码指示状态的一般条件（例如成功完成、警告或信息），子类代码提供有关条件的更详细信息，例如分类和消息。

下表列出了 Neo4j 定义的 GQLSTATUS 代码组及其含义

表 4. Neo4j 定义的 GQLSTATUS 代码组
GQLSTATUS 代码	描述
01N0[y]	弃用警告
01N3[y]	提示警告
01N4[y]	不支持的警告
01N5[y]	无法识别的警告
01N6[y]	通用警告
01N7[y]	安全警告
03N9[y]	性能信息
03N6[y]	通用信息
00N5[y]	成功完成下无法识别的信息
00N6[y]	成功完成下的通用信息
00N7[y]	成功完成下的安全信息
00N8[y]	成功完成下的拓扑信息

服务器通知分组和过滤

所有服务器通知都按类别（在 GqlStatusObject 框架中称为分类）和严重性级别分组，严重性级别可以是 WARNING、WARNING OR INFORMATION 或 INFORMATION 中的一个。

用于按类别和严重性过滤通知的驱动程序端通知配置对于 Neo4j Notification 和 GQL 状态对象框架都是相同的。驱动程序可以按类别/分类和严重性级别过滤通知，服务器只会发送与驱动程序端配置匹配的通知。

驱动程序也可以选择忽略通知。但是，根据 GQLSTATUS 框架，服务器必须始终发送主 GQL 状态对象。因此，如果通知已关闭或通知配置筛选设置为筛选所有通知，服务器仍将发送主 GQL 状态对象，其状态为成功完成、省略结果或无数据。

Neo4j 中存在以下通知组，按严重性排序

表 5. 通知组和严重性级别
类别/分类	严重性	说明	建议的操作
`弃用`	`警告`	查询或命令使用了应替换的已弃用功能。	更新以使用新功能。
`提示`	`警告`	给定的提示无法满足。	删除提示或修复查询，以便可以使用提示。
`不支持`	`警告`	查询或命令尝试使用当前系统不支持的功能或使用不应在生产环境中使用的实验性功能。	不支持的功能不可信，不应在生产环境中使用。
`无法识别`	`警告或信息`	查询或命令提到了系统未知的实体。	确保您没有拼写错误的实体。
`安全`	`警告或信息`	查询或命令的结果表明存在潜在的安全问题。	确保行为符合您的预期。
`拓扑`	`信息`	执行数据库和服务器相关命令时提供的信息。
`模式`	`信息`	管理索引和约束时提供的信息。
`通用`	`警告或信息`	不属于更广泛类别的通知。	取决于特定的通知。
`性能`	`信息`	查询使用了代价高昂的操作，可能会很慢。考虑是否可以以不同的方式重写查询。

通知内部

服务器和驱动程序通过 Bolt 协议相互通信。在握手过程中，它们同意使用服务器和驱动程序都支持的最新可能的 Bolt 协议版本。有关不同服务器版本支持的 Bolt 版本的更多信息，请参阅Bolt 协议文档。

在服务器端，通知是结果核心 API 的一部分。名为getNotifications()的方法返回服务器端通知对象的列表。然后，这些通知作为成功 Bolt 消息元数据发送到驱动程序。在驱动程序端，通知是 ResultSummary API 的一部分，该 API 具有名为notifications()的方法，该方法返回驱动程序端 Notification 对象的列表。getCode()或code()方法的结果称为 Neo4j 状态代码。驱动程序端通知配置在驱动程序和会话级别按严重性和/或类别筛选通知。有关更多信息，请参阅服务器通知分组和筛选。

从 5.23 版本开始，除了现有的 Notification API 之外，Neo4j 还具有新的 GqlStatusObject API。这可以通过在 Result Core API 中使用.getGqlStatusObjects()方法或使用最新的 Neo4j 驱动程序来使用。

服务器-驱动程序版本兼容性

GqlStatusObject API 在服务器端的 Neo4j 5.22 及更高版本以及驱动程序端的 5.23 驱动程序及更高版本中可用。当前的 Notification API 仍然存在，并且可以与之并行使用 GqlStatusObject API。

要充分利用 GqlStatusObject API，您的服务器和驱动程序都必须支持它。低于 5.23 的驱动程序仅发送来自 Notification API 的通知，即使服务器是 5.22 或更高版本。

如果 5.23 或更高版本的驱动程序与过旧的服务器通信（该服务器不知道 GQL 状态对象），则驱动程序需要使用信息填充 GqlStatusObject API。驱动程序尝试从返回的记录数和列数推断出成功、省略结果或无数据。如果失败，则通用 GQLSTATUS 代码将设置为02N42。然后，驱动程序使用来自旧通知 API 的通知填充其余的 GQL 状态对象列表。对于严重性为警告的通知，这些通知将获得 GQLSTATUS 01N42，对于严重性为信息的通知，将获得 GQLSTATUS 03N42。最后，根据GQL 状态通知对象中描述的 GQL 优先级规则对填充的 GQL 状态对象列表进行排序。

表 6. GQLSTATUS 兼容性代码
GQLSTATUS	条件	子条件	描述
01N42	警告	未知警告	严重性为`警告`的填充通知。
02N42	无数据	未知子条件	无法推断出`成功`、`省略结果`或`无数据`时的填充通用状态。
03N42	信息	未知通知	严重性为`信息`的填充通知。