Bolt 协议消息规范

消息规范描述了成功进行 Bolt 握手后在连接上发生的消息交换。有关建立连接和执行握手的详细信息，请参阅Bolt 协议握手规范。

Bolt 协议通过特定版本化的消息进行通信。

Bolt 协议服务器状态规范

对于服务器，使用 Bolt 协议的每个连接在其生命周期中将处于几种状态之一。此状态用于确定客户端可以执行哪些操作。

有关更多信息，请参阅相应版本的Bolt 协议服务器状态规范。

服务器信号

提前跳转表示该信号在消息队列中处理任何消息之前立即可用。

服务器信号提前跳转描述

服务器信号	提前跳转	描述
`<INTERRUPT`>	X	中断信号
`<DISCONNECT>`		断开连接信号

<INTERRUPT>

中断信号

<DISCONNECT>

断开连接信号

协议错误

如果服务器或客户端根据本文档中描述的转换收到意外的消息类型，则必须将其视为协议错误。协议错误是致命的，应立即将服务器状态转换为DEFUNCT，关闭任何开放连接。

会话

与服务器的每个连接都会创建一个新的会话，该会话一直持续到该连接关闭。每个会话都是隔离的，服务器会根据该会话中交换的请求和响应来跟踪当前状态。当该连接的套接字关闭时，会话结束。通常，这将由客户端关闭。

消息交换

消息在客户端和服务器之间以请求-响应模式交换。每个请求仅包含一条消息，每个响应包含零条或多条详细消息，后跟且仅有一条摘要消息。响应中是否存在详细消息直接与已发送的请求消息类型相关。换句话说，某些请求消息类型会引发可能包含详细消息的响应，而其他则不会。

消息也可以进行流水线处理。换句话说，客户端可以主动发送多个请求，而无需首先等待响应。在这种情况下发生故障时，服务器必须忽略所有后续请求，直到客户端明确确认收到故障为止。这可以防止意外执行可能无效的查询。有关此过程的更多详细信息，请参见以下部分。

序列化

消息及其内容使用PackStream 规范版本 1序列化到网络流中。每条消息都表示为一个 PackStream 结构，其中包含固定数量的字段。消息类型由 PackStream 结构标签字节表示，每条消息都在 Bolt 协议中定义。序列化使用 PackStream 版本 1 规范。

分块

分块层也应用于消息传输，作为更可预测地管理数据包的方式。分块过程允许将消息分解成一个或多个任意大小的片段，并将这些片段在单独的块中传输。每个块由一个两字节的头部组成，详细说明了块的大小（以字节为单位），后跟块数据本身。块头部是16 位无符号整数，这意味着允许的最大理论块大小为 65,535 字节。

每个编码消息必须以零大小的块结束，即

00 00

这用于向接收方发出消息边界信号，允许完整接收数据块而无需立即解析消息。这也允许接收和处理未知消息类型而不会破坏消息链。

Bolt 协议使用分块传输编码对每条消息进行编码。

每条消息作为一个或多个数据块传输。
每个块都以一个两字节的头部开始，这是一个无符号大端 16 位整数，表示不包括头部在内的块大小。
一条消息可以跨多个块分割，允许客户端和服务器传输大型消息，而无需提前确定整个消息的长度。
分块单独应用于每条消息。
一个块不能包含多条消息。
每条消息以两个值为 00 00 的字节结束，这些不计入块大小（您可以将它们视为大小为 0 的单个块）。
从版本4.1+开始，NOOP块（空块）用于发送空块，目的是支持连接上的保持活动行为。

Bolt 如何分块消息的示例

单个块中消息的示例

包含 16 字节的消息数据

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

结果如下块

00 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00 00

块头部为00 10，结束标记为00 00。

消息分为两个块的示例

包含 20 字节的消息数据

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 01 02 03 04

结果为块 1 和块 2

00 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00 04 01 02 03 04 00 00

块 1 头部为00 01，块 1 没有结束标记，仍然是消息数据。块 2 头部为00 04，结束标记为00 00。

两个消息的示例

消息 1 数据包含 16 字节

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

消息 2 数据包含 8 字节

0F 0E 0D 0C 0B 0A 09 08

均采用分块编码

00 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00 00
00 08 0F 0E 0D 0C 0B 0A 09 08 00 00

两个消息之间带有NOOP的示例

消息 1 数据包含 16 字节

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

消息 2 数据包含 8 字节

0F 0E 0D 0C 0B 0A 09 08

两个消息使用分块编码，中间带有一个NOOP（空块）

00 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00 00
00 00
00 08 0F 0E 0D 0C 0B 0A 09 08 00 00

流水线

客户端可以主动发送多个请求，而无需首先等待响应。

事务

事务是原子工作单元的概念。

事务的概念是当服务器处于READY状态时，事务通过请求消息RUN打开，并响应摘要消息SUCCESS。事务通过请求消息PULL_ALL或请求消息DISCARD_ALL的摘要消息SUCCESS成功关闭。

Bolt 协议版本3引入了自动提交事务和显式事务的概念。自动提交事务是服务器处于READY状态并转换为STREAMING状态。事务通过请求消息RUN打开，并响应摘要消息SUCCESS。

自动提交事务通过请求消息PULL_ALL或请求消息DISCARD_ALL的摘要消息SUCCESS成功关闭。因此，自动提交事务只能包含一个RUN请求消息。

在 Bolt 协议版本4中，DISCARD_ALL和PULL_ALL消息被重命名为DISCARD和PULL，并引入了新字段。

Bolt v4示例

...
C: HELLO ...
S: SUCCESS ...  // Server is in READY state

C: RUN ...      // Open a new Auto-commit Transaction
S: SUCCESS ...  // Server is in STREAMING state

C: PULL ...
S: RECORD ...
   ...
S: RECORD ...
S: SUCCESS {"has_more": true, ...}  // Server is still in STREAMING state

C: PULL
S: RECORD ...
   ...
S: RECORD ...
S: SUCCESS {"has_more": false, ...}  // Server is in READY state and this implies that the Auto-commit Transaction is closed.

在版本1中，HELLO被称为INIT，自动提交事务就是事务。字段has_more=true/false在版本4中引入。另请参阅相应版本的Bolt 协议服务器状态规范。

显式事务在 Bolt 版本3中引入，它是一种更通用的事务，可以包含多个RUN请求消息。显式事务的概念是当服务器处于READY状态时，事务通过请求消息BEGIN打开，并响应摘要消息SUCCESS（因此转换为TX_READY服务器状态）。

显式事务通过请求消息COMMIT和摘要消息SUCCESS成功关闭。客户端必须在服务器可以转换为TX_READY状态并因此能够使用COMMIT请求消息关闭事务之前完全消费或丢弃结果流（详细消息）。它可以通过请求消息ROLLBACK优雅地丢弃并设置为初始服务器状态READY。

Bolt v4示例

...
C: HELLO ...
S: SUCCESS ...  // Server is in READY state

C: BEGIN ...    // Open a new Explicit Transaction
S: SUCCESS ...  // Server is in TX_READY state

C: RUN ...
S: SUCCESS {"qid": 123, ...} // Server is in TX_STREAMING state, one stream is open

C: RUN ...
S: SUCCESS {"qid": 456, ...} // Server is in TX_STREAMING state, two streams are open

C: PULL {"qid": 123, ...}
S: RECORD ...
   ...
S: RECORD ...
S: SUCCESS {"has_more": true, ...}  // Server is still in TX_STREAMING state, two streams are still open

C: PULL {"qid": 123, ...}
S: RECORD ...
   ...
S: RECORD ...
S: SUCCESS ... has_more=false  // Server is still in TX_STREAMING state, one stream is still open

C: PULL {"qid": 456, ...}
S: RECORD ...
   ...
S: RECORD ...
S: SUCCESS {"has_more": false, ...}  // Server is in TX_READY state, all streams have been fully consumed

C: COMMIT   // Close the Explicit Transaction
S: SUCCESS  // Server is in READY state

在版本3中，PULL被称为PULL_ALL。此外，Bolt 协议版本 3 中没有字段，例如qid=123和has_more=true/false。

更多消息交换示例可在附录 — 消息交换示例中找到。

消息

有三种不同类型的消息

请求消息 - 客户端发送一条消息。
摘要消息 - 如果连接仍然开放，服务器总是响应一条摘要消息。
详细消息 - 服务器总是在发送摘要消息之前响应零条或多条详细消息。

消息签名消息类型字段描述

消息	签名	消息类型	字段	描述
`HELLO`	`01`	请求	`extra::Dictionary(user_agent::String, routing::Dictionary(address::String), notifications_minimum_severity::String, notifications_disabled_categories::List<String>, bolt_agent::Dictionary(product::String, platform::String, language::String, language_details::String))`	初始化连接（替换v1和v2的`INIT`）（`routing::Dictionary(address::String)`在v4.1中添加）（`notifications_minimum_severity::String, notifications_disabled_categories::List<String>`在v5.2中添加）（`bolt_agent::Dictionary`在v5.3中添加）
`LOGON`	`6A`	请求	`scheme::String, …`	验证您随消息发送的用户
`LOGOFF`	`6B`	请求		注销当前用户，准备接收另一个`LOGON`消息
`TELEMETRY`	`54`	请求	`api::Integer`	传输使用遥测数据（在v5.4中添加）
`GOODBYE`	`02`	请求		关闭连接，触发`<DISCONNECT>`信号
`ACK_FAILURE` (仅限v1和v2)	`0E`	请求		确认失败响应（已弃用，v3+请改用`RESET`）
`RESET`	`0F`	请求		重置连接，触发`<INTERRUPT>`信号
`RUN`	`10`	请求	`query::String, parameters::Dictionary, extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db:String, notifications_minimum_severity::String, notifications_disabled_categories::List<String>)`	执行查询（`extra::Dictionary`在v3中添加）（`db:String`在v4.0中添加）（`notifications_minimum_severity::String, notifications_disabled_categories::List<String>`在v5.2中添加）
`DISCARD`	`2F`	请求	`extra::Dictionary(n::Integer, qid::Integer)`	丢弃记录（替换v1、v2和v3的`DISCARD_ALL`）（字段在v4.0中添加）
`PULL`	`3F`	请求	`extra::Dictionary(n::Integer, qid::Integer)`	获取记录（替换v1、v2和v3的`PULL_ALL`）（字段在v4.0中添加）
`BEGIN`	`11`	请求	`extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String, imp_user::String, notifications_minimum_severity::String, notifications_disabled_categories::List<String>)`	开始新事务（在v3中添加）（`db::String, imp_user::String`在v4.0中添加）（`notifications_minimum_severity::String, notifications_disabled_categories::List<String>`在v5.2中添加）
`COMMIT`	`12`	请求		提交事务（在v3中添加）
`ROLLBACK`	`13`	请求		回滚事务（在v3中添加）
`ROUTE`	`66`	请求	`routing::Dictionary(address::String), bookmarks::List<String>, extra::Dictionary(db::String, imp_user::String)`	获取当前路由表（在v4.3中添加）
`SUCCESS`	`70`	摘要	`metadata::Dictionary`	请求成功
`IGNORED`	`7E`	摘要		请求被忽略
`FAILURE`	`7F`	摘要	`metadata::Dictionary`	请求失败
`RECORD`	`71`	详细信息	`data::List`	数据值

HELLO

01

请求

extra::Dictionary(user_agent::String, routing::Dictionary(address::String), notifications_minimum_severity::String, notifications_disabled_categories::List<String>, bolt_agent::Dictionary(product::String, platform::String, language::String, language_details::String))

初始化连接（替换v1和v2的INIT）（routing::Dictionary(address::String)在v4.1中添加）（notifications_minimum_severity::String, notifications_disabled_categories::List<String>在v5.2中添加）（bolt_agent::Dictionary在v5.3中添加）

LOGON

6A

请求

scheme::String, …

验证您随消息发送的用户

LOGOFF

6B

请求

注销当前用户，准备接收另一个LOGON消息

TELEMETRY

54

请求

api::Integer

传输使用遥测数据（在v5.4中添加）

GOODBYE

02

请求

关闭连接，触发<DISCONNECT>信号

ACK_FAILURE (仅限v1和v2)

0E

请求

确认失败响应（已弃用，v3+请改用RESET）

RESET

0F

请求

重置连接，触发<INTERRUPT>信号

RUN

10

请求

query::String, parameters::Dictionary, extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db:String, notifications_minimum_severity::String, notifications_disabled_categories::List<String>)

执行查询（extra::Dictionary在v3中添加）（db:String在v4.0中添加）（notifications_minimum_severity::String, notifications_disabled_categories::List<String>在v5.2中添加）

DISCARD

2F

请求

extra::Dictionary(n::Integer, qid::Integer)

丢弃记录（替换v1、v2和v3的DISCARD_ALL）（字段在v4.0中添加）

PULL

3F

请求

extra::Dictionary(n::Integer, qid::Integer)

获取记录（替换v1、v2和v3的PULL_ALL）（字段在v4.0中添加）

BEGIN

11

请求

extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String, imp_user::String, notifications_minimum_severity::String, notifications_disabled_categories::List<String>)

开始新事务（在v3中添加）（db::String, imp_user::String在v4.0中添加）（notifications_minimum_severity::String, notifications_disabled_categories::List<String>在v5.2中添加）

COMMIT

12

请求

提交事务（在v3中添加）

ROLLBACK

13

请求

回滚事务（在v3中添加）

ROUTE

66

请求

routing::Dictionary(address::String), bookmarks::List<String>, extra::Dictionary(db::String, imp_user::String)

获取当前路由表（在v4.3中添加）

SUCCESS

70

摘要

metadata::Dictionary

请求成功

IGNORED

7E

摘要

请求被忽略

FAILURE

7F

摘要

metadata::Dictionary

请求失败

RECORD

71

详细信息

data::List

数据值

请求消息`HELLO`

在 Bolt 3 中引入

HELLO消息请求连接被授权用于远程数据库，并替换版本1和2的INIT请求消息。有关INIT的更多信息，请参阅下文。

服务器必须处于CONNECTED状态才能处理HELLO消息。对于任何其他状态，接收到HELLO请求必须被视为协议违规并导致连接关闭。

客户端应在连接后立即向服务器发送HELLO消息，并在以任何其他方式使用该连接之前处理相应的响应。

希望重试初始化的客户端应建立新连接。

在版本4.1中，添加了routing::Dictionary(address::String)以指示服务器是否应根据给定的路由上下文执行路由。

在版本5.2中，添加了notifications_minimum_severity::String和notifications_disabled_categories::List<String>以控制通知配置。禁用类别或严重性允许服务器跳过这些分析，从而可以加快查询执行速度。

在版本5.3中，添加了bolt_agent::Dictionary以指示底层驱动程序及其版本，而不是user_agent中使用驱动程序的应用程序。

在版本5.1之前的版本上，LOGON消息中描述的身份验证令牌应作为HELLO消息的一部分发送。

routing 值描述

`routing` 值	描述
`{"routing": null}` 或 `{}`	服务器不应执行路由
`{"routing": {}}`	服务器应执行路由
`{"routing": {"address": "x.example.com:9001", "region": "example", …}}`	服务器应根据给定的路由上下文执行路由

{"routing": null} 或 {}

服务器不应执行路由

{"routing": {}}

服务器应执行路由

{"routing": {"address": "x.example.com:9001", "region": "example", …}}

服务器应根据给定的路由上下文执行路由

签名：01

字段

extra::Dictionary(
  scheme::String,
  ...
  user_agent::String,
  patch_bolt::List<String>,
  routing::Dictionary(address::String),
  notifications_minimum_severity::String,
  notifications_disabled_categories::List<String>,
  bolt_agent::Dictionary(
    product::String,
    platform::String,
    language::String,
    language_details::String
  )
)

scheme是身份验证方案，以及所选方案特有的任何其他条目（...）。预定义方案包括："none"、"basic"、"bearer"、"kerberos"（取决于服务器的功能）。有关更多信息，请参阅LOGON消息。在 bolt 5.0 之后移除
user_agent应符合"名称/版本"格式，例如"Example/4.1.0"（有关更多信息，请参阅https://mdn.org.cn/en-US/docs/Web/HTTP/Headers/User-Agent）。驱动程序应允许应用程序代码设置此值，因为它旨在标识使用驱动程序的应用程序。
patch_bolt允许驱动程序请求服务器对协议进行修补。在服务器在SUCCESS响应中确认之前，不得应用该修补程序。默认值：[]。在 bolt 4.3 中引入在 bolt 4.4 之后移除
- "utc"是目前唯一支持的补丁。如果成功协商，服务器和驱动程序将使用 Bolt 版本5.0中定义的DateTime和DateTimeZoneId。
routing字段应包含路由上下文信息和地址字段，其中应包含客户端最初尝试连接的地址，例如"x.example.com:9001"。路由上下文中的键值条目应与原始 URI 查询字符串中的条目完全对应。将routing设置为null表示服务器不应执行任何路由。默认值：null。在 bolt 4.1 中引入
notifications_minimum_severity指定通知需要达到的最低严重性才能被返回。请参阅状态码 → 服务器通知分组和过滤以了解可接受的条目，协议中添加了特殊值"OFF"，它禁用所有通知。发送null将使服务器使用其配置的默认值。默认值：null。在 bolt 5.2 中引入
notifications_disabled_categories是不会被返回的通知类别列表。请参阅状态码 → 服务器通知分组和过滤以了解可用类别。发送null将使服务器使用其配置的默认值。默认值：null。在 bolt 5.2 中引入
bolt_agent::Dictionary与user_agent相反，旨在标识驱动程序而不是使用它的应用程序。驱动程序不应允许应用程序更改此值。在填充字段时，驱动程序应注意不要包含任何可用于标识单个机器或用户的信息。此字段是强制性的。在 bolt 5.3 中引入
- product::String应符合"名称/版本"格式，并标识驱动程序，例如"neo4j-fortran-alice-doe/42.69.0"。此字段是强制性的。
- platform::String应描述驱动程序运行的平台，例如"Linux 5.15.0-58-generic; x86_64"。如果无法获得平台信息，则发送null（或省略）。默认值：null。
- language::String应符合"名称/版本"格式，并描述驱动程序/应用程序所用的语言，例如"Fortran/77"。如果无法获得语言信息，则发送null（或省略）。默认值：null。
- language_details::String可包含有关驱动程序/应用程序所用语言的更多信息，例如编译器、运行时或解释器及其 respective 版本。如果无法获得语言详细信息，则发送null（或省略）。默认值：null。

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
FAILURE

示例

概要

HELLO {extra}

示例 1

HELLO {"user_agent": "Example/4.1.0", "routing": {"address": "x.example.com:9001"}, "bolt_agent": {"product": "neo4j-fortran-alice-doe/42.69.0", "platform": "Linux 5.15.0-58-generic; x86_64", "language": "Fortran/77", "language_details": "gfortran 9.3.0"}}

示例 2

HELLO {"user_agent": "Example/4.2.0", "patch_bolt": ["utc"], "routing": {"address": "x.example.com:9001", "policy": "example_policy_routing_context", "region": "example_region_routing_context"}, "notifications_minimum_severity": "WARNING", "notifications_disabled_categories": ["HINT", "GENERIC"]}

服务器响应`SUCCESS`

SUCCESS消息响应表示客户端被允许交换更多消息。服务器可以包含描述服务器环境和/或连接详细信息的元数据。

为包含在SUCCESS元数据中定义了以下字段

server::String（服务器代理字符串，例如"Neo4j/4.1.0"）
connection_id::String（服务器端使用的 bolt 连接的唯一标识符，例如："bolt-61"）
patch_bolt::List<String> 仅当客户端在请求的patch_bolt字段中请求了补丁时。如果服务器支持，它将包含请求的补丁子集（与客户端请求的字符串完全相同）。从那时起，服务器-客户端通信必须仅使用打补丁的协议。在 bolt 4.3 中引入在 bolt 4.4 之后移除
hints::Dictionary（一组可选配置提示，供驱动程序酌情考虑以增强适用操作）在 bolt 4.3 中引入

hints字典可能包含一组可选的配置提示，驱动程序可自行决定解释或忽略这些提示，以在适用情况下增强操作。可用提示的完整列表可在附录 — 连接提示中找到。提示在给定连接的整个生命周期内保持有效且无法更改。因此，随着服务器配置的调整，新建立的连接可能会观察到不同的提示和/或提示值。

示例

SUCCESS {"server": "Neo4j/4.0.0", "hints": {"connection.recv_timeout_seconds": 120}}

示例 2

SUCCESS {"server": "Neo4j/4.4.0", "patch_bolt": ["utc"], "hints": {"connection.recv_timeout_seconds": 120}}

服务器响应`FAILURE`

FAILURE消息响应表示客户端不允许交换更多消息。服务器可以选择包含描述故障性质的元数据，但必须在发送故障后立即关闭连接。

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1+

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`INIT`

在 bolt 1 中引入在 bolt 2 之后移除

INIT消息是请求连接被授权用于远程数据库。

请求消息INIT仅在版本1和2中有效，并在版本3+中被请求消息HELLO取代。

INIT消息使用结构签名01并传递两个字段：user agent（字符串）和auth_token（字典）。

服务器必须处于CONNECTED状态才能处理INIT请求。对于任何其他状态，接收到INIT请求将被视为协议违规并导致连接关闭。

客户端应在连接后立即向网络发送INIT请求，并在以任何其他方式使用该连接之前处理相应的响应。

接收服务器可以选择注册或以其他方式记录用户代理，但如果愿意也可以忽略它。

身份验证令牌应由服务器用于确定客户端是否被允许交换更多消息。如果此身份验证失败，服务器必须响应FAILURE消息并立即关闭连接。希望重试初始化的客户端应建立新连接。

签名：01

字段

user_agent::String,
auth_token::Dictionary(
  scheme::String,
  principal::String,
  credentials::String,
)

user_agent应符合"名称/版本"格式，例如"Example/1.1.0"（有关更多信息，请参阅https://mdn.org.cn/en-US/docs/Web/HTTP/Headers/User-Agent）。
scheme是身份验证方案。预定义方案为"none"和"basic"。如果未提供scheme，则默认为"none"。
auth_token必须仅包含条目{"scheme" : "none"}或包含键scheme、principal和credentials。

详细消息

不应返回详细消息。

有效摘要消息

SUCCESS
FAILURE

示例

概要

INIT "user_agent" {auth_token}

示例 1

INIT "Example/1.0.0" {"scheme": "none"}

示例 2

INIT "Example/1.0.0" {"scheme": "basic", "principal": "neo4j", "credentials": "password"}

服务器响应`SUCCESS`

SUCCESS消息响应表示客户端被允许交换更多消息。服务器可以包含描述服务器环境和/或连接详细信息的元数据。

为包含在SUCCESS元数据中定义了以下字段。

server::String（服务器代理字符串，例如"Neo4j/3.4.0"）

示例

SUCCESS {"server": "Neo4j/3.4.0"}

服务器响应`FAILURE`

FAILURE消息响应表示客户端不允许交换更多消息。

服务器可以选择包含描述故障性质的元数据，但必须在发送故障后立即关闭连接。

示例

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`LOGON`

在 bolt 5.1 中引入

LOGON消息承载身份验证请求。

此消息是版本5.1中的新增消息。在以前的版本中，身份验证是HELLO消息的一部分。

签名：6A

字段

auth::Dictionary(
  scheme::String,
  ...
)

scheme是身份验证方案。预定义方案为none、basic、bearer和kerberos（取决于服务器的能力）。
消息中的其他条目会传递给所选身份验证方案的实现。它们的名称、类型和默认值取决于该选择。
- 方案basic需要用户名principal::String和密码credentials::String。
- 方案bearer仅需要令牌credentials::String。

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
FAILURE

如果身份验证失败，服务器将响应FAILURE消息并立即关闭连接。

示例

概要

LOGON {auth}

示例 1

LOGON {"scheme": "basic", "principal": "user", "credentials": "password"}

服务器响应`SUCCESS`

SUCCESS消息响应表示客户端已成功通过身份验证。

为包含在SUCCESS元数据中定义了以下字段。

advertised_address::String? - 数据库服务器的配置的广告地址。在 bolt 5.8 中引入
credentials_expired::Boolean - 发送的凭据已过期，用户必须更新它们。如果此字段不存在，则应将其视为false。

示例 v5.8+

SUCCESS {"advertised_address": "graphz.example.com:7687"}

示例 v5.1+

SUCCESS {}

请求消息`LOGOFF`

在 bolt 5.1 中引入

LOGOFF消息注销当前已通过身份验证的用户。连接随后即可接收另一个LOGON消息。

此消息是版本5.1中的新增消息。在以前的版本中不存在等效消息。

签名：6B

字段：无字段

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
FAILURE

示例

概要

LOGOFF

示例

LOGOFF

服务器响应`SUCCESS`

如果已成功接收到LOGOFF消息请求，服务器应响应SUCCESS消息并进入AUTHENTICATION状态。

示例

SUCCESS {}

服务器响应`FAILURE`

如果在服务器未处于READY状态时接收到LOGOFF消息，则应触发FAILURE，随后立即关闭连接。服务器可以向消息附加元数据，以提供有关故障性质的更多详细信息。收到对LOGOFF响应的FAILURE的客户端应将该连接视为DEFUNCT并处置它。

示例 v5.7+

FAILURE {"code": "Neo.ClientError.Request.Invalid", "message": "Message 'LogoffMessage{}' cannot be handled by a session in the FAILED state."}

示例 v5.1+

FAILURE {"neo4j_code": "Neo.ClientError.Request.Invalid", "message": "Message 'LogoffMessage{}' cannot be handled by session in the READY state", "gql_status": "08N06", "description": "error: connection exception - protocol error. General network protocol error.", "diagnostic_record": {"_classification": "CLIENT_ERROR"}, "cause": {"message": "08N10: Message LogoffMessage{} cannot be handled by session in the 'READY' state.", "gql_status": "08N10", "description": "error: connection exception - invalid server state. Message LogoffMessage{} cannot be handled by session in the 'READY' state.", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}}

请求消息`TELEMETRY`

在 bolt 5.4 中引入

TELEMETRY消息包含一个整数，表示使用了哪个驱动程序 API。

遥测信息存储在服务器的指标系统中。客户端收到SUCCESS响应，除非它为api字段发送了无效值，这将导致FAILURE响应。

客户端应提供用户禁用发送遥测数据的选项。此外，服务器可以通过在HELLO消息的SUCCESS消息中发送相应的配置提示来选择不接收来自客户端的遥测数据。有关更多信息，请参阅附录 — 连接提示。如果客户端忽略该提示，服务器仍必须接受TELEMETRY消息。

消息只能在READY状态下发送。

签名：54

字段

api::Integer

api的有效值和相应的 API 关联是

0 — 托管事务
1 — 显式事务
2 — 隐式事务
3 — 驱动程序级execute_query()

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
FAILURE

示例

概要

TELEMETRY api

示例 1

TELEMETRY 0

服务器响应`SUCCESS`

如果成功收到TELEMETRY消息请求，服务器将响应SUCCESS并保持其当前状态。

示例

SUCCESS {}

服务器响应`FAILURE`

如果TELEMETRY消息包含无效的api值或在错误状态下发送，服务器将响应FAILURE消息并进入FAILED状态。

示例 1 v5.7+

C: TELEMETRY 2
S: FAILURE {"neo4j_code": "Neo.ClientError.Request.Invalid", "message": "Message of type TelemetryMessage cannot be handled by a session in the NEGOTIATION state.", "gql_status": "50N42", "description": "error: general processing exception - unexpected error. Unexpected error has occurred. See debug log for details."}

示例 1 v5.4+

C: TELEMETRY 2
S: FAILURE {"code": "Neo.ClientError.Request.Invalid", "message": "Message of type TelemetryMessage cannot be handled by a session in the NEGOTIATION state."}

示例 2 v5.7+

C: TELEMETRY "oh no!"
S: FAILURE {"neo4j_code": "Neo.ClientError.Request.Invalid", "message": "Unexpected type: Expected INT but got STRING", "gql_status": "22G03", "description": "error: data exception - invalid value type", "cause": {"message": "22N01: Expected the value 128 to be of type INT, but was of type STRING.", "gql_status": "22N01", "description": "error: data exception - invalid type. Expected the value 128 to be of type INT, but was of type STRING.", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}}

示例 2 v5.4+

C: TELEMETRY "oh no!"
S: FAILURE {"code": "Neo.ClientError.Request.Invalid", "message": "Unexpected type: Expected INT but got STRING"}

示例 3 v5.7+

C: TELEMETRY 9001
S: FAILURE {"neo4j_code": "Neo.DatabaseError.General.UnknownError", "message": "org.neo4j.packstream.error.reader.PackstreamReaderException: Unknown driver interface type 9001", "gql_status": "50N00", "description": "error: general processing exception - internal error. Internal exception raised DecoderException: org.neo4j.packstream.error.reader.PackstreamReaderException: Unknown driver interface type 9001", "cause": {"message": "50N09: The server transitioned into a server state that is not valid in the current context: 'uncaught error'.", "gql_status": "50N09", "description": "error: general processing exception - invalid server state transition. The server transitioned into a server state that is not valid in the current context: 'uncaught error'.", "diagnostic_record": {"_classification": "DATABASE_ERROR"}}}

示例 3 v5.4+

C: TELEMETRY 9001
S: FAILURE {"code": "Neo.DatabaseError.General.UnknownError", "message": "org.neo4j.packstream.error.reader.PackstreamReaderException: Unknown driver interface type 9001"}

请求消息`GOODBYE`

在 Bolt 3 中引入

GOODBYE消息通知服务器连接正在正常终止。收到此消息后，服务器应立即关闭其端的套接字而不发送响应。

客户端在发送GOODBYE消息后可以随时关闭套接字。此消息会中断服务器的当前工作（如果有）。

签名：02

字段：无字段。

详细消息

不应返回详细消息。

有效的摘要消息

不应返回摘要消息。

示例

概要

GOODBYE

示例

GOODBYE

请求消息`ACK_FAILURE`

在 bolt 1 中引入在 bolt 2 之后移除

请求消息ACK_FAILURE向服务器发出信号，表明客户端已确认先前的故障并应返回到READY状态。

请求消息ACK_FAILURE仅在版本1和2中有效，在版本3+中应使用请求消息RESET代替。

签名：0E

字段：无字段。

详细消息:

不应返回详细消息。

有效的摘要消息

SUCCESS
FAILURE

服务器必须处于FAILED状态才能成功处理ACK_FAILURE请求。对于任何其他状态，接收到ACK_FAILURE请求将被视为协议违规并导致连接关闭。

示例

概要

ACK_FAILURE

示例

ACK_FAILURE

服务器响应`SUCCESS`

如果已成功接收到ACK_FAILURE请求，服务器应响应SUCCESS消息并进入READY状态。

服务器可以向SUCCESS消息附加元数据。

示例

SUCCESS {}

服务器响应消息`FAILURE`

如果在未处于FAILED状态时接收到ACK_FAILURE请求，服务器应响应FAILURE消息并立即关闭连接。

服务器可以向消息附加元数据以提供有关故障性质的更多详细信息。

示例

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`RESET`

在 bolt 1 中引入

RESET消息请求将连接重置回其初始RESET状态，就像刚成功完成HELLO（v1和v2中的INIT）（以及v5.1+中的LOGON）一样。RESET消息的独特之处在于，它在到达服务器时会跳过消息队列，停止正在执行的任何工作单元。然后，RESET消息之前队列中的所有消息都将被IGNORED，直到达到RESET位置。从此时起，服务器状态将重置为准备好新会话的状态。

在版本1和2中，RESET消息分为两个独立的信号。首先，<INTERRUPT>信号会跳过消息队列，停止正在执行的任何工作单元，并将状态机置于INTERRUPTED状态。其次，RESET与所有其他传入消息一起排队，并用于在其处理轮次到达时将状态机恢复到READY状态。这本质上意味着INTERRUPTED状态仅在RESET到达消息队列和稍后在适当位置处理该RESET之间暂时存在。因此，INTERRUPTED状态是唯一无需客户端进一步输入即可自动解决且其进入不会生成响应消息的状态。

签名：0F

字段：无字段

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
FAILURE

示例

概要

RESET

示例

RESET

服务器响应`SUCCESS`

如果成功接收到RESET消息请求，服务器应响应SUCCESS消息并进入READY状态。

示例

SUCCESS {}

服务器响应`FAILURE`

如果在服务器进入READY状态之前收到RESET消息，它将触发FAILURE，随后立即关闭连接。服务器可以向消息附加元数据，以提供有关故障性质的更多详细信息。收到对RESET响应的FAILURE的客户端应将该连接视为DEFUNCT并处置它。

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1-v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`RUN`

在 bolt 1 中引入

RUN消息请求执行 Cypher 查询，并附带一组参数和附加的额外数据。

在版本3+中，此消息可用于显式事务或自动提交事务。事务类型由消息序列暗示

显式事务：首先使用BEGIN启动事务上下文后的RUN。
自动提交事务：未首先使用BEGIN启动显式事务的RUN。

签名：10

字段

query::String,
parameters::Dictionary,
extra::Dictionary(
  bookmarks::List<String>,
  tx_timeout::Integer,
  tx_metadata::Dictionary,
  mode::String,
  db::String,
  imp_user::String,
  notifications_minimum_severity::String,
  notifications_disabled_categories::List<String>
)

query可以是任何 Cypher 查询（包括过程调用）。
parameters是用于query字符串的参数dictionary。

显式事务（BEGIN+RUN）的 extra 字段不带任何数据。

对于自动提交事务（RUN），extra 字段包含

extra包含附加选项。在 bolt 3 中引入
- bookmarks是包含某种书签标识的字符串列表，例如["neo4j-bookmark-transaction:1", "neo4j-bookmark-transaction:2"]。默认值：[]。
- tx_timeout是一个整数，指定事务超时时间（毫秒）。默认值：服务器端配置的超时时间。
- tx_metadata是一个字典，可以包含一些元数据信息，主要用于日志记录。默认值：null。
- mode指定RUN消息的目标服务器类型。写入访问使用"w"，读取访问使用"r"。默认值："w"。
- db指定多数据库的数据库名称，用于选择事务发生的位置。null和""表示服务器端配置的默认数据库。默认值：null。在 bolt 4.0 中引入
- imp_user键指定执行此事务的模拟用户。null表示不模拟（作为当前用户执行）。默认值：null。在 bolt 4.4 中引入
- notifications_minimum_severity指定通知需要达到的最低严重性才能被返回。请参阅状态码 → 服务器通知分组和过滤以了解可接受的条目，协议中添加了特殊值"OFF"，它禁用所有通知。发送null将使服务器使用当前连接的HELLO消息中指定的任何值。默认值：null。在 bolt 5.2 中引入
- notifications_disabled_categories是不会被返回的通知类别列表。请参阅状态码 → 服务器通知分组和过滤以了解可用类别。发送null将使服务器使用当前连接的HELLO消息中指定的任何值。默认值：null。在 bolt 5.2 中引入

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

服务器必须处于READY或READY_TX（v3+）状态才能成功处理RUN请求。 如果服务器处于FAILED或INTERRUPTED状态，请求将被IGNORED。 对于任何其他状态，接收到RUN请求将被视为协议违规并导致连接关闭。

示例

概要

RUN "query" {parameters} {extra}

示例 1

RUN "RETURN $x AS x" {"x": 1} {"bookmarks": [], "tx_timeout": 123, "tx_metadata": {"log": "example_message"}, "mode": "r"}

示例 2

RUN "RETURN $x AS x" {"x": 1} {}

示例 3

RUN "CALL dbms.procedures()" {} {}

示例 3

RUN "RETURN 42" {} {"notifications_minimum_severity": "WARNING", "notifications_disabled_categories": ["HINT", "GENERIC"]}

服务器响应`SUCCESS`

SUCCESS消息响应表示客户端被允许交换更多消息。

为包含在SUCCESS元数据中定义了以下字段。

fields::List<String>，返回结果的字段。例如 [“name”, “age”, …]
t_first::Integer，结果流中第一条记录可用后的时间，以毫秒为单位。

对于隐式事务（RUN）

db::String? - 解析后的用户主数据库，事务将在此数据库中运行。此字段仅在客户端未明确提供数据库以启动事务时才存在。在 bolt 5.8 中引入

对于显式事务（BEGIN+RUN）

qid::Integer指定服务器分配的语句 ID，以在BEGIN`RUN`PULL和BEGIN`RUN`DISCARD消息中引用服务器端结果集。在 bolt 4.0 中引入

示例 v4.0+

SUCCESS {"fields": ["x"], "t_first": 123, "qid": 7000}

示例 v3+

SUCCESS {"fields": ["x"], "t_first": 123}

对于v1和v2，如果成功接收到RUN请求并且服务器认为其有效，则服务器应响应SUCCESS消息并进入STREAMING状态。 服务器可以向消息附加元数据，以提供后续结果的头部详细信息。 客户端不应将SUCCESS响应视为查询执行完成的标志，而仅视为其被接受。 元数据中包含以下字段：

`fields` (例如 ["name", "age"])
`result_available_after` (例如 123)

示例 v1 和 v2

SUCCESS {"fields": ["x"], "result_available_after": 123}

服务器响应`IGNORED`

示例

IGNORED

服务器响应`FAILURE`

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`DISCARD`

在 bolt 1 中引入

DISCARD消息请求丢弃结果流的其余部分。

在v1、v2和v3中，此消息称为DISCARD_ALL，无字段，并发出请求以丢弃未完成的结果并返回到READY状态。 接收服务器不应中止请求，而应继续处理它，而不将任何详细消息流回客户端。

签名：2F

字段

extra::Dictionary(
  n::Integer,
  qid::Integer
)

extra包含附加选项。在 bolt 4.0 中引入
- n指定要丢弃多少条记录。n=-1将丢弃所有记录。n没有默认值，必须存在。
- qid（查询标识）指定要执行操作的语句（仅限显式事务）。qid=-1可用于表示最后执行的语句。默认值：-1。

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

示例

概要

DISCARD {extra}

示例 1

DISCARD {"n": -1, "qid": -1}

示例 2

DISCARD {"n": 1000}

示例 3 v1、v2 或 v3

DISCARD_ALL

在版本1和2中，服务器必须处于STREAMING或STREAMING_TX（v3+）状态才能成功处理DISCARD请求。如果服务器处于FAILED状态或INTERRUPTED状态，请求将被IGNORED。对于任何其他状态，接收到DISCARD请求将被视为协议违规并导致连接关闭。

服务器响应`SUCCESS`

has_more::Boolean，如果还有更多记录要流式传输，则为true。如果此字段不存在，则应将其视为默认为false。在 bolt 4.0 中引入

或者在has_more为false的情况下

bookmark::String — 提交此事务后的书签（仅限自动提交事务）。
db::String — 执行查询的数据库名称。在 bolt 4.0 中引入
notifications::List<Dictionary> — 执行此语句期间生成的所有通知的列表。如果不存在通知，则可以省略。在v3中，此字段为notifications::Dictionary。在 bolt 3 中引入在 bolt 5.4 之后移除
statuses::List<Dictionary> — 执行此语句期间生成的所有 gqlStatusObjects 的列表。在 bolt 5.6 中引入
plan::Dictionary — 计划结果。在 bolt 3 中引入
profile::Dictionary — 概要结果。在 bolt 3 中引入
result_consumed_after::Integer — 与t_last相同。在 bolt 2 之后移除
result_available_after::Integer — 与t_first相同。在 bolt 2 之后移除
stats::Dictionary — 计数器信息，例如数据库命中等。在 bolt 3 中引入
t_last::Integer — 结果流中最后一条记录被消费后的时间（毫秒）。在 bolt 3 中引入
t_first::Integer — DBMS 准备流式传输结果中第一条记录后的时间（毫秒）。在 bolt 3 中引入
type::String — 语句类型，例如只读语句的"r"，只写语句的"w"，读写语句的"rw"，以及仅模式的"s"。在 bolt 3 中引入

示例 1 v4+

SUCCESS {"has_more": true}

示例 2 v4+

SUCCESS {"bookmark": "example-bookmark:1", "db": "example_database"}

示例 v3

SUCCESS {"bookmark": "example-bookmark:1"}

在版本1和2中，如果已成功接收到DISCARD_ALL请求，服务器应响应SUCCESS消息并进入READY状态。

示例 v1 和 v2

SUCCESS {"bookmark": "example_bookmark_identifier", "result_consumed_after": 123}

请求消息`PULL`

PULL消息请求从结果流的其余部分获取数据。

在v1、v2和v3中，此消息称为PULL_ALL，且无字段。在v1和v2中，此消息发出请求，将未完成的结果流回客户端，然后返回到READY状态。结果详情包括在摘要消息之前发送零条或多条详细消息。此协议版本定义了一条此类详细消息，即RECORD（如下所述）。

签名：3F

字段

extra::Dictionary(
  n::Integer,
  qid::Integer
)

extra包含附加选项。在 bolt 4.0 中引入
- n指定要获取多少条记录。n=-1将获取所有记录。n没有默认值，必须存在。
- qid（查询标识）指定要执行操作的语句（仅限显式事务）。qid=-1可用于表示最后执行的语句。默认值：-1。

详细消息

零条或多条RECORD。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

示例

概要

PULL {extra}

概要 v1 - v3

PULL_ALL

示例 1

PULL {"n": -1, "qid": -1}

示例 2

PULL {"n": 1000}

示例 v1 - v3

PULL_ALL

服务器响应`SUCCESS`

为包含在SUCCESS元数据中定义了以下字段

has_more::Boolean，如果还有更多记录要流式传输，则为true。如果此字段不存在，则应将其视为默认为false。

或者在has_more为false的情况下

bookmark::String — 提交此事务后的书签（仅限自动提交事务）。
db::String — 执行查询的数据库名称。在 bolt 4.0 中引入
notifications::List<Dictionary> — 执行此语句期间生成的所有通知的列表。如果不存在通知，则可以省略。在v3中，此字段为notifications::Dictionary。在 bolt 5.4 之后移除
statuses::List<Dictionary> — 执行此语句期间生成的所有 gqlStatusObjects 的列表。在 bolt 5.6 中引入
plan::Dictionary — 计划结果。在 bolt 3 中引入
profile::Dictionary — 概要结果。在 bolt 3 中引入
result_consumed_after::Integer — 与t_last相同。在 bolt 2 之后移除
result_available_after::Integer — 与t_first相同。在 bolt 2 之后移除
stats::Dictionary — 计数器信息，例如数据库命中等。在 bolt 3 中引入
t_last::Integer — 结果流中最后一条记录被消费后的时间（毫秒）。在 bolt 3 中引入
t_first::Integer — 结果流中第一条记录可用后的时间（毫秒）。在 bolt 3 中引入
type::String — 语句类型，例如只读语句的"r"，只写语句的"w"，读写语句的"rw"，以及仅模式的"s"。在 bolt 3 中引入

示例 v3+

SUCCESS {"bookmark": "example-bookmark:1", "t_last": 123}

示例 v1 - v2

SUCCESS {"bookmark": "example_bookmark_identifier", "result_consumed_after": 123}

服务器响应`IGNORED`

对于v1和v2，服务器在FAILED状态或INTERRUPTED状态下接收到PULL_ALL请求时，应响应IGNORED消息并丢弃请求而不进行处理。不应发生状态更改。

示例

IGNORED

服务器响应`FAILURE`

对于v1和v2，如果PULL_ALL消息请求无法成功处理，服务器应响应FAILURE消息并进入FAILED状态。服务器可以向消息附加元数据以提供有关故障性质的更多详细信息。

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

服务器响应`RECORD`（在v1和v2中）

在拖尾摘要消息之前，响应PULL_ALL可能会返回零条或多条RECORD消息。每条记录都带有一个值列表，构成记录的数据内容。列表中值的顺序对客户端应该有意义，可能基于该结果的请求顺序，但不能保证结果中记录的顺序。只有在后面跟着SUCCESS摘要消息时，记录才应被视为有效。在收到此摘要之前，记录的有效性应被视为暂定。

示例

RECORD [1, 2, 3]

请求消息`BEGIN`

在 bolt 1 中引入

BEGIN消息请求创建新的显式事务。此消息之后应跟随RUN消息。显式事务通过COMMIT消息或ROLLBACK消息关闭。

签名：11

字段

extra::Dictionary(
  bookmarks::List<String>,
  tx_timeout::Integer,
  tx_metadata::Dictionary,
  mode::String,
  db::String,
  imp_user::String,
  notifications_minimum_severity::String,
  notifications_disabled_categories::List<String>
)

bookmarks是包含某种书签标识的字符串列表，例如 ["neo4j-bookmark-transaction:1", "neo4j-bookmark-transaction:2"]。默认值：[]。
tx_timeout是一个整数，指定事务超时时间（毫秒）。默认值：服务器端配置的超时时间。
tx_metadata是一个字典，可以包含一些元数据信息，主要用于日志记录。默认值：null。
mode指定RUN消息的目标服务器类型。写入访问使用"w"，读取访问使用"r"。如果未发送模式，则默认为写入访问。默认值："w"。
db指定多数据库的数据库名称，用于选择事务发生的位置。null和""表示服务器端配置的默认数据库。默认值：null。在 bolt 4.0 中引入
imp_user键指定执行此事务的模拟用户。null表示不模拟（作为当前用户执行）。默认值：null。在 bolt 4.4 中引入
notifications_minimum_severity指定通知需要达到的最低严重性才能被返回。请参阅状态码 → 服务器通知分组和过滤以了解可接受的条目，协议中添加了特殊值"OFF"，它禁用所有通知。发送null将使服务器使用当前连接的HELLO消息中指定的任何值。默认值：null。在 bolt 5.2 中引入
notifications_disabled_categories是不会被返回的通知类别列表。请参阅状态码 → 服务器通知分组和过滤以了解可用类别。发送null将使服务器使用当前连接的HELLO消息中指定的任何值。默认值：null。在 bolt 5.2 中引入

详细消息

无详细消息。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

示例

概要

BEGIN {extra}

示例 1

BEGIN {"tx_timeout": 123, "mode": "r", "db": "example_database", "tx_metadata": {"log": "example_log_data"}, "imp_user" : "bob"}

示例 2

BEGIN {"db": "example_database", "tx_metadata": {"log": "example_log_data"}, "bookmarks": ["example-bookmark:1", "example-bookmark2"]}

示例 3

BEGIN {"notifications_minimum_severity": "WARNING", "notifications_disabled_categories": ["HINT", "GENERIC"]}

服务器响应`SUCCESS`

为包含在SUCCESS元数据中定义了以下字段

db::String? - 解析后的用户主数据库，事务将在此数据库中运行。此字段仅在客户端未明确提供数据库以启动事务时才存在。在 bolt 5.8 中引入

示例

SUCCESS {}

带有主数据库解析的示例

SUCCESS {"db": "my_home_db"}

服务器响应`IGNORED`

示例

IGNORED

服务器响应`FAILURE`

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`COMMIT`

COMMIT消息请求显式事务完成。

COMMIT消息在v1和v2中不存在。

签名：12

字段：无字段。

详细消息

无详细消息。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

示例

概要

COMMIT

示例

COMMIT

服务器响应`SUCCESS`

SUCCESS消息响应表示显式事务已完成

bookmark::String，提交此事务后的书签。

示例

SUCCESS {"bookmark": "example-bookmark:1"}

服务器响应`IGNORED`

示例

IGNORED

服务器响应`FAILURE`

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`ROLLBACK`

ROLLBACK消息请求显式事务回滚。

ROLLBACK消息在v1和v2中不存在。

签名：13

字段：无字段。

详细消息

无详细消息。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

示例

概要

ROLLBACK

示例

ROLLBACK

服务器响应`SUCCESS`

SUCCESS消息响应表示显式事务已回滚。

示例

SUCCESS

服务器响应`IGNORED`

示例

IGNORED

服务器响应`FAILURE`

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

请求消息`ROUTE`

在 bolt 4.3 中引入

ROUTE指示服务器返回当前路由表。在以前的版本中没有为此目的的显式消息，必须通过RUN和PULL消息使用 Cypher 调用过程。

此消息只能在成功身份验证后且在事务外部发送。

签名：66

字段

routing::Dictionary,
bookmarks::List<String>,
db::String,
extra::Dictionary(
  db::String,
  imp_user::String,
)

请注意，在v4.4中，db参数被迁移到一个名为extra的专用字典中，该字典还包含imp_user，因此，在v4.3中，字段是

routing::Dictionary,
bookmarks::List<String>,
db::String

路由字段应包含路由上下文信息和地址字段，其中应包含客户端最初尝试连接的地址，例如"x.example.com:9001"。路由上下文中的键值条目应与原始 URI 查询字符串中的条目完全对应。
bookmarks是包含某种书签标识的字符串列表，例如 ["neo4j-bookmark-transaction:1", "neo4j-bookmark-transaction:2"]。
db指定多数据库的数据库名称，用于选择事务发生的位置。null表示服务器端配置的默认数据库。在 bolt 4.3 之后移除
extra包含附加选项。在 bolt 4.4 中引入
- db如上。默认值：null。
- imp_user指定用于解析其主数据库的模拟用户。null表示不模拟（作为当前用户执行）。默认值：null。

详细消息

不应返回详细消息。

有效的摘要消息

SUCCESS
IGNORED
FAILURE

示例

概要

ROUTE {routing} [bookmarks] {extra}

示例 v4.4+

ROUTE {"address": "x.example.com:9001", "policy": "example_policy_routing_context", "region": "example_region_routing_context"} ["neo4j-bookmark-transaction:1", "neo4j-bookmark-transaction:2"] {"db": "example_database", "imp_user": "bob"}

示例 v4.3

ROUTE {"address": "x.example.com:7687"} [] null

服务器响应`SUCCESS`

SUCCESS消息响应表示客户端被允许交换更多消息。以下字段被定义为包含在SUCCESS元数据中

rt::Dictionary(ttl::Integer, db::String, servers::List<Dictionary(addresses::List<String>, role::String)>)，当前路由表。
- ttl::Integer指定此路由表应被视为有效的秒数。
- db::String标识此路由表适用的数据库。在 bolt 4.4 中引入
- servers具有类型为Dictionary(addresses::List<String>, role::String)的三个元素，其中role为"ROUTE"、"READ"、"WRITE"，每个元素恰好对应一个条目。

示例 v4.4+

SUCCESS {
    "rt": {"ttl": 1000,
           "db": "foo",
           "servers": [{"addresses": ["localhost:9001"], "role": "ROUTE"},
                       {"addresses": ["localhost:9010", "localhost:9012"], "role": "READ"},
                       {"addresses": ["localhost:9020", "localhost:9022"], "role": "WRITE"}]}
}

示例 v4.3

SUCCESS {
    "rt": {"ttl": 1000,
           "servers": [{"addresses": ["localhost:9001"], "role": "ROUTE"},
                       {"addresses": ["localhost:9010", "localhost:9012"], "role": "READ"},
                       {"addresses": ["localhost:9020", "localhost:9022"], "role": "WRITE"}]}
}

服务器消息`IGNORED`

示例

IGNORED

服务器消息`FAILURE`

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v4.3 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

摘要消息`SUCCESS`

SUCCESS消息表示相应的请求已按预期成功。它可能包含与结果相关的元数据。元数据键在本文档中与开始交换的消息相关的部分中描述。

签名：70

字段

metadata::Dictionary

示例

概要

SUCCESS {metadata}

示例

SUCCESS {"example": "see specific message for server response metadata"}

摘要消息`IGNORED`

IGNORED消息表示相应的请求尚未执行。

签名：7E

字段：无字段。

示例

概要

IGNORED

示例

IGNORED

摘要消息`FAILURE`

签名：7F

字段

metadata::Dictionary

元数据中定义了以下字段

message::String - 故障的人类可读描述。
code::String - 标识故障的 neo4j 代码。在 bolt 5.6 之后移除
neo4j_code::String - 标识故障的 neo4j 代码。在 bolt 5.7 中引入
gql_status::String - 标识错误的 GQL 状态。应优先使用此字段而不是neo4j_code。有关GQL 状态通知对象的更多信息，请参阅。在 bolt 5.7 中引入
description::String - 描述由gql_status表示的故障。在 bolt 5.7 中引入
diagnostic_record::Dictionary - 包含用于帮助诊断状态的字段。内容为默认值时省略。在 bolt 5.7 中引入
- OPERATION::String - GQL 标准字段。默认值：""
- OPERATION_CODE::String - GQL 标准字段。默认值："0"
- CURRENT_SCHEMA::String - GQL 标准字段。默认值："/"
- _classification::String? - 对故障进行分类。
cause:Dictionary(message::String, gql_status::String, description::String, diagnostic_record::Dictionary, cause::Dictionary?)? - 错误的内部原因。此字段提供了关于故障的更具体的详细信息和上下文。在 bolt 5.7 中引入

diagnostic_record 字段可能包含额外的和未文档化的条目。这些信息对于诊断故障可能很重要。

示例

概要

FAILURE {metadata}

示例 v5.7+

FAILURE {"gql_status": "01N00", "message": "old message you have failed something", "description": "default condition - default subcondition. Message", "neo4j_code": "Example.Failure.Code", "diagnostic_record": {"_classification": "CLIENT_ERROR"}}

示例 v1 - v5.6

FAILURE {"code": "Example.Failure.Code", "message": "example failure"}

详细消息 `RECORD`

RECORD 消息携带一系列值，对应于结果中的单个条目。

签名： 71

这些消息目前仅在响应 PULL（在 v1、v2 和 v3 中为 PULL_ALL）消息时接收，并且总是紧跟着一个摘要消息。

示例

概要

RECORD [data]

示例 1

RECORD ["1", "2", "3"]

示例 2

RECORD [{"point": [1, 2]}, "example_data", 123]

各版本更改摘要

以下部分列出了消息与前一版本相比的更改。另请检查结构语义中的更改。

版本 5.8

引入连接提示 ssr.enabled
引入 advertised_address 作为 LOGON 的响应元数据
事务开始消息（BEGIN 或 RUN）的 SUCCESS 消息包含解析后的主数据库作为 db。

版本 5.7

FAILURE 消息已更改为包含 gql_status、description、diagnostic_record 和 cause。code 已重命名为 neo4j_code。

版本 5.6

包含 notifications 字段的 SUCCESS 消息已更改为包含 statuses 字段。
- PULL 上的 SUCCESS
- DISCARD 上的 SUCCESS

版本 5.5

不支持的（且未文档化的 😏）协议版本

版本 5.5 仅在某些驱动程序中发布，但设计有缺陷。没有 Neo4j 服务器会协商此协议版本。

版本 5.4

新增消息 TELEMETRY。

版本 5.3

HELLO 消息的 extra 字典中新增字段 bolt_agent。

版本 5.2

HELLO、BEGIN 和 RUN 消息现在接受通知选项 notifications_minimum_severity 和 notifications_disabled_categories。

版本 5.1

HELLO 消息不再接受身份验证。
LOGON 消息已添加并接受身份验证。
LOGOFF 消息已添加。

版本 5

与版本 4.4 相比无变化

版本 4.4

ROUTE 消息中的 db 参数已迁移到一个名为 extra 的专用字典中。
imp_user 参数已分别添加到 ROUTE、RUN 和 BEGIN 消息的元字段中。

版本 4.3

当连接在服务器忙于处理请求时长时间保持空闲状态时，NOOP 数据块现在可以在所有连接状态下传输。
在响应 HELLO 命令时传输的 SUCCESS 结构的元数据属性中添加了一个额外的提示字典，以向驱动程序提供可选的配置提示。
新增消息 ROUTE 用于查询路由表。

版本 4.2

与版本 4.1 相比无变化。

版本 4.1

HELLO 消息定义了子字段 routing::Dictionary(address::String)，用于指示是否应执行服务器端路由并可以包含路由上下文数据。
支持 NOOP 数据块（空数据块）。服务器和客户端都应支持此功能。

版本 4.0

DISCARD_ALL 消息重命名为 DISCARD 并引入了新字段。
PULL_ALL 消息重命名为 PULL 并引入了新字段。
BEGIN 消息现在包含字段 db::String 以指定数据库名称。
RUN 消息现在包含字段 db::String 以指定数据库名称。
显式事务（BEGIN+RUN）现在可以获得带有 SUCCESS 和元数据键 qid（查询标识）的服务器响应。
DISCARD 消息现在可以丢弃任意数量的记录。新增字段 n 和 qid。
DISCARD 消息现在可以获得带有 SUCCESS 和元数据键 has_more 的服务器响应。
PULL 消息现在可以获取任意数量的记录。新增字段 n 和 qid。
PULL 消息现在可以获得带有 SUCCESS 和元数据键 has_more 的服务器响应。

版本 3

INIT 请求消息已替换为 HELLO 消息。
ACK_FAILURE 请求消息已移除。请改用 RESET 消息。
RUN 消息中新增 extra::Dictionary 字段。
BEGIN 消息中新增 extra::Dictionary 字段。
新的 HELLO 请求消息。
新的 GOODBYE 请求消息。
新的 BEGIN 请求消息。
新的 COMMIT 请求消息。
新的 ROLLBACK 请求消息。
新的 RESET 请求消息。

版本 2

与版本 1 相比无变化。

Bolt 协议消息规范

Bolt 协议服务器状态规范

服务器信号

协议错误

会话

消息交换

序列化

分块

Bolt 如何分块消息的示例

流水线

事务

消息

请求消息HELLO

示例

服务器响应SUCCESS

服务器响应FAILURE

请求消息INIT

示例

服务器响应`SUCCESS`

服务器响应`FAILURE`

请求消息LOGON

示例

服务器响应SUCCESS

请求消息LOGOFF

示例

服务器响应SUCCESS

服务器响应FAILURE

请求消息TELEMETRY

示例

服务器响应SUCCESS

服务器响应FAILURE

请求消息GOODBYE

示例

请求消息ACK_FAILURE

示例

服务器响应`SUCCESS`

服务器响应消息`FAILURE`

请求消息RESET

示例

服务器响应SUCCESS

服务器响应FAILURE

请求消息RUN

示例

服务器响应SUCCESS

服务器响应IGNORED

服务器响应FAILURE

请求消息DISCARD

示例

服务器响应SUCCESS

请求消息PULL

示例

服务器响应SUCCESS

服务器响应IGNORED

服务器响应FAILURE

服务器响应RECORD（在v1和v2中）

请求消息BEGIN

示例

服务器响应SUCCESS

服务器响应IGNORED

服务器响应FAILURE

请求消息COMMIT

示例

服务器响应SUCCESS

服务器响应IGNORED

服务器响应FAILURE

请求消息ROLLBACK

示例

服务器响应SUCCESS

服务器响应IGNORED

服务器响应FAILURE

请求消息ROUTE

示例

服务器响应SUCCESS

服务器消息IGNORED

服务器消息FAILURE

摘要消息SUCCESS

示例

摘要消息IGNORED

示例

摘要消息FAILURE

请求消息`HELLO`

服务器响应`SUCCESS`

服务器响应`FAILURE`

请求消息`INIT`

请求消息`LOGON`

服务器响应`SUCCESS`

请求消息`LOGOFF`

服务器响应`SUCCESS`

服务器响应`FAILURE`

请求消息`TELEMETRY`

服务器响应`SUCCESS`

服务器响应`FAILURE`

请求消息`GOODBYE`

请求消息`ACK_FAILURE`

请求消息`RESET`

服务器响应`SUCCESS`

服务器响应`FAILURE`

请求消息`RUN`

服务器响应`SUCCESS`

服务器响应`IGNORED`

服务器响应`FAILURE`

请求消息`DISCARD`

服务器响应`SUCCESS`

请求消息`PULL`

服务器响应`SUCCESS`

服务器响应`IGNORED`

服务器响应`FAILURE`

服务器响应`RECORD`（在v1和v2中）

请求消息`BEGIN`

服务器响应`SUCCESS`

服务器响应`IGNORED`

服务器响应`FAILURE`

请求消息`COMMIT`

服务器响应`SUCCESS`

服务器响应`IGNORED`

服务器响应`FAILURE`

请求消息`ROLLBACK`

服务器响应`SUCCESS`

服务器响应`IGNORED`

服务器响应`FAILURE`

请求消息`ROUTE`

服务器响应`SUCCESS`

服务器消息`IGNORED`

服务器消息`FAILURE`

摘要消息`SUCCESS`

摘要消息`IGNORED`

摘要消息`FAILURE`

详细消息 `RECORD`