服务器通知

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

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

本页面介绍 GQL 状态对象和 Neo4j 通知框架、它们的结构、它们提供的通知对象以及如何解释它们。它还解释了服务器通知的分组和过滤、通知内部机制以及 Notification 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()，或在驱动端使用相应的方法。对于某些有用的字段，还提供了额外的辅助方法。

字段

描述

操作

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

操作码

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

当前模式

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

_严重级别

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

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

_分类

通知的 Neo4j 类别。

_位置

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

_状态参数

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

成功通用代码

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]	安全警告
03N9[y]	性能信息
03N6[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 Notification 和 GQL 状态对象框架中是相同的。驱动程序可以按类别/分类和严重级别过滤通知，并且服务器将仅发送与驱动端配置匹配的通知。

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

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

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

通知内部机制

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

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

从 5.23 版本开始，除了现有的 Notification API 外，Neo4j 还引入了新的 GqlStatusObject API。可以在 Result Core API 中使用 .getGqlStatusObjects() 方法或使用最新的 Neo4j 驱动程序来使用此 API。Notification API 自 Neo4j 5.26 起已弃用。

服务器-驱动版本兼容性

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

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

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

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