服务器通知

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

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

本页介绍了 GQL-status 对象和 Neo4j 通知框架、它们的结构、它们提供的通知对象以及如何解读它们。此外，还说明了服务器通知的分组和过滤、通知内部机制，以及通知 API 和 GqlStatusObject API 在服务器与驱动程序之间的兼容性。

GQL-status 通知对象

在 GQL-status 对象框架中，当用户向服务器执行查询时，总会产生一个称为执行结果 (execution outcome) 的输出。如果执行过程中未发生错误，则结果记录为完成条件，表示成功执行并产生了常规的非空结果、省略结果或无数据。它以 GQL-status 对象列表的形式呈现，这些对象根据以下优先级规则进行组织，列表中第一个对象为主要 GQL-status 对象：

NO DATA（无数据）优先于 WARNING（警告）。
WARNING（警告）优先于 SUCCESSFUL COMPLETION（成功完成）子类。
SUCCESSFUL COMPLETION（成功完成）子类优先于 INFORMATIONAL（信息）。
INFORMATIONAL（信息）是优先级最低的条件。

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

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

每个 GQL-status 对象包含以下字段：

GQLSTATUS 代码

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

StatusDescription

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

DiagnosticRecord

关于状态的额外信息，以键值对形式提供（在服务器端和驱动程序端均适用）。要获取完整的诊断记录，可以在服务器端使用 diagnosticRecord()，或在驱动程序端使用相应的方法。针对某些有用字段，还提供了额外的辅助方法。

字段

描述

OPERATION

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

OPERATION_CODE

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

CURRENT_SCHEMA

与通知相关的当前架构。始终默认为 /。

_severity

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

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

_classification

通知的 Neo4j 类别。

_position

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

成功通用代码

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-status 对象，在此情况下，由驱动程序进行填充（请参阅服务器与驱动程序兼容性）。

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-status 通知对象
在 5.26 版本中已弃用

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

通知对象包含以下字段：

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

服务器通知分组和过滤

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

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

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

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

表 5. 通知组与严重级别
类别/分类	严重性	解释	建议的操作
`DEPRECATION（弃用）`	`WARNING`	查询或命令使用了应被替换的弃用功能。	更新以使用新功能。
`HINT（提示）`	`WARNING`	无法满足给定的提示。	移除提示或修复查询，以便可以使用该提示。
`UNSUPPORTED`	`WARNING`	查询或命令尝试使用当前系统不支持的功能，或使用了不应在生产环境中使用的实验性功能。	不支持的功能不可信，不应在生产环境中使用。
`UNRECOGNIZED（无法识别）`	`WARNING OR INFORMATION`	查询或命令提到了系统未知的实体。	确保没有拼写错误。
`SECURITY`	`WARNING OR INFORMATION`	查询或命令的结果表明存在潜在的安全问题。	确保行为符合您的预期。
`TOPOLOGY`	`INFORMATION`	执行数据库和服务器相关命令时提供的信息。
`模式 (SCHEMA)`	`INFORMATION`	管理索引和约束时提供的信息。
`GENERIC（通用）`	`WARNING OR INFORMATION`	不属于更广泛类别的通知。	取决于具体的通知。
`PERFORMANCE（性能）`	`INFORMATION`	查询使用了高开销操作，可能运行缓慢。考虑是否可以用不同方式重写查询。

通知内部机制
在 5.26 版本中已弃用

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

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

从 5.23 版本开始，除了现有的通知 API 外，Neo4j 还引入了新的 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-status 对象的旧版本服务器，驱动程序需要使用信息来填充 GqlStatusObject API。驱动程序尝试根据返回的记录和列数推断 SUCCESS、OMITTED RESULT 或 NO DATA。如果推断失败，通用的 GQLSTATUS 代码将被设置为 02N42。然后，驱动程序使用旧通知 API 中的通知填充其余的 GQL-status 对象列表。严重性为 WARNING 的通知将获得 GQLSTATUS 01N42，严重性为 INFORMATION 的通知将获得 03N42。最后，填充后的 GQL-status 对象列表将根据GQL-status 通知对象中描述的 GQL 优先级规则进行排序。

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