服务器通知

成功执行查询后，Neo4j 服务器会发送通知，以提供有关查询执行的额外信息，或就如何提高查询质量提供建议。驱动程序接收这些通知，并将其发送到 Neo4j 工具（例如 Browser、Bloom、Cypher Shell）或用户应用程序，由它们向用户显示。

从 5.23 版本开始，Neo4j 除了现有的通知 API（自 5.26 版本起已弃用）外，还新增了一个 GqlStatusObject API。GqlStatusObject API 提供有关 Cypher 查询或命令执行状态的信息，符合 ISO/IEC 39075:2024(en) - 信息技术 - 数据库语言 - GQL 标准。

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

GQL 状态通知对象

在 GQL 状态对象框架中，当用户向服务器执行查询时，它总是产生一个称为 执行结果 的结果。如果在执行过程中没有发生错误，结果将记录为完成条件，表示成功的结果，其中包含常规非空结果、省略结果或无数据。它表示为 GQL 状态对象列表，这些对象根据以下优先级规则组织，其中列表中的第一个对象是主要的 GQL 状态对象

NO DATA 优先于 WARNING。
WARNING 优先于 SUCCESSFUL COMPLETION 子类。
SUCCESSFUL COMPLETION 子类优先于 INFORMATIONAL。
INFORMATIONAL 是优先级最低的条件。

有关 SUCCESSFUL COMPLETION、NO DATA 或 OMITTED RESULT 的更多信息，请参阅成功的一般代码。
GQL 状态对象可以包含多个 GQL 状态对象，其中每个对象代表查询执行的不同条件。主要的 GQL 状态对象描述了优先级最高的条件，并且始终存在。列表中所有其他 GQL 状态对象都是附加的 GQL 状态对象。

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

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

GQLSTATUS 代码

一个 5 字符的字符串，由一个 2 字符的类代码和随后的一个 3 字符的子类代码串联而成，用于标识通知的条件。

状态描述

GQLSTATUS 的人类可读描述，包括一个条件、一个子条件以及关于该条件的附加可选文本。条件和子条件分别是类代码和子类代码的文本表示。

诊断记录

关于状态的额外信息，以键值对的形式提供，包括服务器端和驱动程序端。要检索完整的诊断记录，您可以使用服务器端的 diagnosticRecord() 或驱动程序端的相应方法。此外，还公开了一些有用的字段的辅助方法。

字段

描述

OPERATION (操作)

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

OPERATION_CODE (操作代码)

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

CURRENT_SCHEMA (当前模式)

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

_severity (严重性)

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

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

_classification (分类)

Neo4j 通知类别。

_position (位置)

通知在查询文本中相关的位置，由行和列给出。

_status_parameters (状态参数)

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

成功的一般代码

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

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

GQLSTATUS 一般代码由服务器填充，除非服务器版本过旧无法识别 GQL 状态对象，在这种情况下，它将由驱动程序进行填充（参见服务器-驱动程序兼容性）。

Neo4j 定义的 GQLSTATUS 代码

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

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

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

Neo4j 状态通知对象

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

通知对象包含以下字段

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

服务器通知分组和过滤

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

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

驱动程序也可以选择忽略通知。但是，根据 GQLSTATUS 框架，服务器必须始终发送主要的 GQL 状态对象。因此，如果通知关闭或通知配置过滤设置为过滤掉所有通知，服务器仍将发送状态为 SUCCESSFUL COMPLETION、OMITTED RESULT 或 NO DATA 的主要 GQL 状态对象。

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

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

通知内部机制

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

在服务器端，通知是 Result Core API 的一部分。一个名为 getNotifications() 的方法（自 5.26 版本起已弃用）返回服务器端通知对象的列表。然后，这些通知作为成功 Bolt 消息元数据发送到驱动程序。在驱动程序端，通知是 ResultSummary API 的一部分，其中有一个名为 notifications() 的方法，它返回驱动程序端通知对象的列表。getCode() 或 code() 方法的结果称为 Neo4j 状态代码。驱动程序端通知配置在驱动程序和会话级别按严重性和/或类别过滤通知。有关更多信息，请参阅服务器通知分组和过滤。

从 5.23 版本开始，Neo4j 除了现有通知 API 外，新增了 GqlStatusObject API。可以通过 Result Core API 中的 .getGqlStatusObjects() 方法或使用最新的 Neo4j 驱动程序来使用它。通知 API 自 Neo4j 5.26 版本起已弃用。

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

GqlStatusObject API 在服务器端从 Neo4j 5.22 及更高版本开始可用，在驱动程序端从 5.23 驱动程序及更高版本开始可用。当前的通知 API 仍然存在，并且 GqlStatusObject API 可以与其并行使用。

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

如果 5.23 或更高版本的驱动程序与无法识别 GQL 状态对象的旧服务器通信，则驱动程序需要使用信息来填充 GqlStatusObject API。驱动程序尝试根据返回的记录数和列数推断出 SUCCESS、OMITTED RESULT 或 NO DATA。如果失败，通用 GQLSTATUS 代码将设置为 02N42。然后，驱动程序将 GQL 状态对象列表的其余部分与旧通知 API 中的通知一起填充。严重性为 WARNING 的通知将获得 GQLSTATUS 01N42，严重性为 INFORMATION 的通知将获得 GQLSTATUS 03N42。最后，填充的 GQL 状态对象列表将根据GQL 状态通知对象中描述的 GQL 优先级规则进行排序。

表 6. GQLSTATUS 兼容性代码
GQLSTATUS	条件	子条件	描述
01N42	警告	未知警告	严重性为 `WARNING` 的填充通知。
02N42	无数据	未知子条件	当无法推断出 `SUCCESS`、`OMITTED RESULT` 或 `NO DATA` 时的填充通用状态。
03N42	信息	未知通知	严重性为 `INFORMATION` 的填充通知。