Bolt Protocol Message Specification - Version 4

Note: Byte values are represented using hexadecimal notation unless otherwise specified.

Version 4.0

Deltas

The changes compared to Bolt protocol version 3 are listed below:

Overview of Major Version Changes

The handshake have been re-specified to support Major and Minor versions.

The concept of multi database support have been introduced with the field db::String for the request message BEGIN and the request message RUN.

Queries within an Explicit Transaction can be consumed out of order with the new behaviour of PULL and DISCARD.

PULL {"n": ?, "qid": ?}

DISCARD {"n": ?, "qid": ?}

The qid is included in the SUCCESS response of a RUN message within an Explicit Transaction (BEGIN+RUN). See Appendix - Example 4.

Bolt Protocol Server State Specification

For the server, each connection using the Bolt Protocol will occupy one of several states throughout its lifetime.

This state is used to determine what actions may be undertaken by the client.

See, Bolt Protocol Server State Specification Version 4

Server Signals

Jump ahead is that the signal will immediately be available before any messages are processed in the message queue.

Server Signal Jump Ahead Description
<INTERRUPT> x an interrupt signal
<DISCONNECT>   a disconnect signal

Protocol Errors

If a server or client receives a message type that is unexpected, according to the transitions described in this document, it must treat that as a protocol error. Protocol errors are fatal and should immediately transition the server state to DEFUNCT, closing any open connections.

Message Exchange

Messages are exchanged in a request-response pattern between client and server.

Each request consists of exactly one message and each response consists of zero or more detail messages followed by exactly one summary message. The presence or absence of detail messages in a response is directly related to the type of request message that has been sent. In other words, some request message types elicit a response that may contain detail messages, others do not.

Messages may also be pipelined. In other words, clients may send multiple requests eagerly without first waiting for responses.

When a failure occurs in this scenario, the server must ignore all subsequent requests until the connection from the server side is in the READY state. This prevents inadvertent execution of queries that may not be valid.

Serialization

Messages and their contents are serialized into network streams using PackStream Specification Version 1.

Each message is represented as a PackStream structure, that contains a fixed number of fields.
Note: conceptually BOLT messages and PackStream structures are not the same. Even though they have the same encoded form, the tags used might overlap. It is recommended to model them separately when implementing the protocol.

The message type is denoted by the PackStream structure tag byte and each message is defined in the Bolt protocol.

Serialization is specified with PackStream Version 1.

Some messages that contain Dictionary fields, define default values for some of the keys. Bandwidth can be saved by omitting these entries if the value equals the default.

Chunking

A layer of chunking is also applied to message transmissions as a way to more predictably manage packets of data.

The chunking process allows the message to be broken into one or more pieces, each of an arbitrary size, and for those pieces to be transmitted within separate chunks.

Each chunk consists of a two-byte header, detailing the chunk size in bytes followed by the chunk data itself. Chunk headers are 16-bit unsigned integers, meaning that the maximum theoretical chunk size permitted is 65,535 bytes.

Each encoded message must be terminated with a chunk of zero size, i.e.

00 00

This is used to signal message boundaries to a receiving parties, allowing blocks of data to be fully received without requiring that the message is parsed immediately. This also allows for unknown message types to be received and handled without breaking the messaging chain.

The Bolt protocol encodes each message using a chunked transfer encoding.

This section provides some examples to illustrate how Bolt chunks messages.

Example: A message in one chunk

Message data containing 16 bytes,

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

The chunk,

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

chunk header: 00 10

end marker: 00 00

Example: A message split in two chunks

Message data containig 20 bytes:

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

chunk 1, chunk 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

chunk 1 header: 00 10

chunk 1 end marker: no end marker, still message data

chunk 2 header: 00 04

chunk 2 end marker: 00 00

Example: Two messages

Message 1 data containing 16 bytes:

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

Message 2 data containing 8 bytes:

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

The two messages encoded with chunking,

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

Pipelining

The client may send multiple requests eagerly without first waiting for responses.

Transaction

A transaction is the concept of atomic units of work.

An Auto-commit Transaction is a basic but limited form of transaction.

The concept of Auto-commit Transaction is when the server is in the READY state and the transaction is opened with the request message RUN and the response of a summary message SUCCESS.

The Auto-commit Transaction is successfully closed with the summary message SUCCESS and not containing the field has_more::true for the request message PULL or DISCARD. Thus the Auto-commit Transaction can only contain one RUN request message.

Example 1:

...
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.

See, Bolt Protocol Server State Specification Version 4

An Explicit Transaction is a more generic transaction that can contain several RUN request messages.

The concept of Explicit Transaction is when the server is in the READY state and the transaction is opened with the request message BEGIN and the response of a summary message SUCCESS (thus transition into the TX_READY server state).

The Explicit Transaction is successfully closed with the request message COMMIT and the response of a summary message SUCCESS. The result stream (detail messages) must be fully consumed or discarded by a client before the server can transition to the TX_READY state and thus be able to close the transaction with a COMMIT request message.

The Explicit Transaction can be gracefully discarded and set to the initial server state of READY with the request message ROLLBACK.

Example 2:

...
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

See, Bolt Protocol Server State Specification Version 4

Messages - Version 4.0

Message Signature Request Message Summary Message Detail Message Fields Description
HELLO 01 x     extra::Dictionary(user_agent::String, scheme::String) initialize connection
GOODBYE 02 x       close the connection, triggers a <DISCONNECT> signal
RESET 0F x       reset the connection, triggers a <INTERRUPT> signal
RUN 10 x     query::String, parameters::Dictionary, extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db:String) execute a query
DISCARD 2F x     extra::Dictionary(n::Integer, qid::Integer) discard records
PULL 3F x     extra::Dictionary(n::Integer, qid::Integer) fetch records
BEGIN 11 x     extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String) begin a new transaction
COMMIT 12 x       commit a transaction
ROLLBACK 13 x       rollback a transaction
SUCCESS 70   x   metadata::Dictionary request succeeded
IGNORED 7E   x     request was ignored
FAILURE 7F   x   metadata::Dictionary(code::String, message::String) request failed
RECORD 71     x data::List data values

Request Message - HELLO

The HELLO message request the connection to be authorized for use with the remote database.

The server must be in the CONNECTED state to be able to process a HELLO message. For any other states, receipt of an HELLO request must be considered a protocol violation and lead to connection closure.

Clients should send HELLO message to the server immediately after connection and process the corresponding response before using that connection in any other way.

If authentication fails, the server must respond with a FAILURE message and immediately close the connection.

Clients wishing to retry initialization should establish a new connection.

Signature: 01

Fields:

extra::Dictionary(
  user_agent::String,
  scheme::String,
  …
)

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

HELLO {user_agent::String, scheme::String}

Example:

HELLO {"user_agent": "Example/4.0.0", "scheme": "basic", "principal": "user-id-1", "credentials": "user-password"}

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages. Servers can include metadata that describes details of the server environment and/or the connection.

The following fields are defined for inclusion in the SUCCESS metadata.

Example:

SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "bolt-61"}

Server Response FAILURE

A FAILURE message response indicates that the client is not permitted to exchange further messages. Servers may choose to include metadata describing the nature of the failure but must immediately close the connection after the failure has been sent.

Example:

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

Request Message - GOODBYE

The GOODBYE message notifies the server that the connection is terminating gracefully.

On receipt of this message, the server should immediately shut down the socket on its side without sending a response.

A client may shut down the socket at any time after sending the GOODBYE message.

This message interrupts the server current work if there is any.

Signature: 02

Fields:

No fields.

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

No summary message should be returned.

Synopsis

GOODBYE

Example:

GOODBYE

Request Message - RESET

The RESET message requests that the connection should be set back to its initial state, as if a HELLO message had just been successfully completed.

The RESET message is unique in that it on arrival at the server, it jumps ahead in the message queue, stopping any unit of work that happens to be executing.

All the queued messages originally in front of the RESET message will then be IGNORED until the RESET position is reached. Then from this point, the server state is reset to a state that is ready for a new session.

Signature: 0F

Fields:

No fields.

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

No summary message should be returned.

Synopsis

RESET

Example:

RESET

Request Message - RUN

The RUN message requests that a Cypher query is executed with a set of parameters and additional extra data.

This message could both be used in an Explicit Transaction or an Auto-commit Transaction. The transaction type is implied by the order of message sequence.

Signature: 10

Fields:

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

An Explicit Transaction (BEGIN+RUN) does not carry any data in the extra field.

For Auto-commit Transaction (RUN) the extra field carries:

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

RUN "query" {parameters} {extra}

Example 1:

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

Example 2:

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

Example 3:

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

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages.

The following fields are defined for inclusion in the SUCCESS metadata.

For Explicit Transaction (BEGIN+RUN):

Example 1:

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

Example 2:

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

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - DISCARD

The DISCARD message requests that the remainder of the result stream should be thrown away.

Signature: 2F

Fields:

extra::Dictionary{
  n::Integer,
  qid::Integer,
}

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

DISCARD {extra}

Example 1:

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

Example 2:

DISCARD {"n": 1000}

Server Response SUCCESS

The following fields are defined for inclusion in the SUCCESS metadata.

or in the case that has_more is false,

Example 1:

SUCCESS {"has_more": true}

Example 2:

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

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - PULL

The PULL message requests data from the remainder of the result stream.

Signature: 3F

Fields:

extra::Dictionary{
  n::Integer,
  qid::Integer,
}

Detail Messages:

Zero or more RECORD

Valid Summary Messages:

Synopsis

PULL {extra}

Example 1:

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

Example 2:

PULL {"n": 1000}

Server Response SUCCESS

The following fields are defined for inclusion in the SUCCESS metadata.

or in the case that has_more is false,

Example 1:

SUCCESS {"has_more": true}

Example 2:

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

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - BEGIN

The BEGIN message request the creation of a new Explicit Transaction.

This message should then be followed by a RUN message.

The Explicit Transaction is closed with either the COMMIT message or ROLLBACK message.

Signature: 11

Fields:

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

Detail Messages:

No detail messages.

Valid Summary Messages:

Synopsis

BEGIN {extra}

Example 1:

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

Example 2:

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

Server Response SUCCESS

Example:

SUCCESS {}

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - COMMIT

The COMMIT message request that the Explicit Transaction is done.

Signature: 12

Fields:

No fields.

Detail Messages:

No detail messages.

Valid Summary Messages:

Synopsis

COMMIT

Example:

COMMIT

Server Response SUCCESS

A SUCCESS message response indicates that the Explicit Transaction was completed.

Example:

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

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - ROLLBACK

The ROLLBACK message requests that the Explicit Transaction rolls back.

Signature: 13

Fields:

No fields.

Detail Messages:

No detail messages.

Valid Summary Messages:

Synopsis

ROLLBACK

Example:

ROLLBACK

Server Response SUCCESS

A SUCCESS message response indicates that the Explicit Transaction was rolled back.

SUCCESS {}

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Summary Message - SUCCESS

The SUCCESS message indicates that the corresponding request has succeeded as intended.

It may contain metadata relating to the outcome.

Metadata keys are described in the section of this document relating to the message that began the exchange.

Signature: 70

Fields:

metadata::Dictionary

Synopsis

SUCCESS {metadata}

Example:

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

Summary Message - IGNORED

The IGNORED message indicates that the corresponding request has not been carried out.

Signature: 7E

Fields:

No fields

Synopsis

IGNORED

Example:

IGNORED

Summary Message - FAILURE

Signature: 7F

Fields:

metadata::Dictionary(
  code::String,
  message::String,
)

Synopsis

FAILURE {metadata}

Example:

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

Detail Message - RECORD

A RECORD message carries a sequence of values corresponding to a single entry in a result.

Signature: 71

These messages are currently only ever received in response to a PULL message and will always be followed by a summary message.

Fields:

data::List

Synopsis

RECORD [data]

Example 1:

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

Example 2:

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

Version 4.1

Deltas

The changes compared to Bolt protocol version 4.0 are listed below:

Overview

Bolt handshake should now timeout (off by default) on the server side.

The initial address that the client knows the server by is sent with the HELLO message to help with routing information. See Appendix - Example 3.

The NOOP chunk (empty chunk) is used to send an empty chunk and the purpose is to be able to support a keep alive behaviour on the connection.

Example: Two messages with a NOOP in between

Message 1 data containing 16 bytes:

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

Message 2 data containing 8 bytes:

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

The two messages encoded with chunking and a NOOP (empty chunk) in between.

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

Messages - Version 4.1

Message Signature Request Message Summary Message Detail Message Fields Description
HELLO 01 x     extra::Dictionary(user_agent::String, scheme::String, routing::Dictionary(address::String)) initialize connection
GOODBYE 02 x       close the connection, triggers a <DISCONNECT> signal
RESET 0F x       reset the connection, triggers a <INTERRUPT> signal
RUN 10 x     query::String, parameters::Dictionary, extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db:String) execute a query
DISCARD 2F x     extra::Dictionary(n::Integer, qid::Integer) discard records
PULL 3F x     extra::Dictionary(n::Integer, qid::Integer) fetch records
BEGIN 11 x     extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String) begin a new transaction
COMMIT 12 x       commit a transaction
ROLLBACK 13 x       rollback a transaction
SUCCESS 70   x   metadata::Dictionary request succeeded
IGNORED 7E   x     request was ignored
FAILURE 7F   x   metadata::Dictionary(code::String, message::String) request failed
RECORD 71     x data::List data values

Request Message - 4.1 - HELLO

The HELLO message requests the connection to be authorized for use with the remote database.

The server must be in the CONNECTED state to be able to process a HELLO message. For any other states, receipt of an HELLO request must be considered a protocol violation and lead to connection closure.

Clients should send HELLO message to the server immediately after connection and process the corresponding response before using that connection in any other way.

If authentication fails, the server must respond with a FAILURE message and immediately close the connection.

Clients wishing to retry initialization should establish a new connection.

The new routing::Dictionary(address::String) field adds an indicator if the server should carry out routing, according to the the given routing context.

routing values Description
{"routing": null} or {} the server should not carry out routing
{"routing: {}} the server should carry out routing
{"routing: {"address": "x.example.com:9001", "region": "example", ...}} the server should carry out routing according to the given routing context

The absence of the routing key is semantically identical to passing a null value (first option).

Signature: 01

Fields:

extra::Dictionary(
  user_agent::String,
  scheme::String,
  routing::Dictionary(address::String),
  …
)

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

HELLO {user_agent::String, scheme::String, routing::Dictionary(address::String))

Example 1:

HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001"}}

Example 2:

HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001", "policy": "example_policy_routing_context", "region": "example_region_routing_context"}}

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages. Servers can include metadata that describes details of the server environment and/or the connection.

The following fields are defined for inclusion in the SUCCESS metadata.

Example:

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

Server Response FAILURE

A FAILURE message response indicates that the client is not permitted to exchange further messages. Servers may choose to include metadata describing the nature of the failure but must immediately close the connection after the failure has been sent.

Example:

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

Version 4.2

Deltas

No changes compared to version 4.1.

Version 4.3

Deltas

The changes compared to Bolt protocol version 4.2 are listed below:

Messages - Version 4.3

Message Signature Request Message Summary Message Detail Message Fields Description
HELLO 01 x     extra::Dictionary(user_agent::String, scheme::String, routing::Dictionary(address::String)) initialize connection
GOODBYE 02 x       close the connection, triggers a <DISCONNECT> signal
RESET 0F x       reset the connection, triggers a <INTERRUPT> signal
RUN 10 x     query::String, parameters::Dictionary, extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db:String) execute a query
DISCARD 2F x     extra::Dictionary(n::Integer, qid::Integer) discard records
PULL 3F x     extra::Dictionary(n::Integer, qid::Integer) fetch records
BEGIN 11 x     extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String) begin a new transaction
COMMIT 12 x       commit a transaction
ROLLBACK 13 x       rollback a transaction
ROUTE 66 x     routing::Dictionary(address::String), bookmarks::List<String>, db:String fetch the current routing table
SUCCESS 70   x   metadata::Dictionary request succeeded
IGNORED 7E   x     request was ignored
FAILURE 7F   x   metadata::Dictionary(code::String, message::String) request failed
RECORD 71     x data::List data values

Request Message - 4.3 - HELLO

The HELLO message requests the connection to be authorized for use with the remote database.

The server must be in the CONNECTED state to be able to process a HELLO message. For any other states, receipt of an HELLO request must be considered a protocol violation and lead to connection closure.

Clients should send HELLO message to the server immediately after connection and process the corresponding response before using that connection in any other way.

If authentication fails, the server must respond with a FAILURE message and immediately close the connection.

Clients wishing to retry initialization should establish a new connection.

Signature: 01

Fields:

extra::Dictionary(
  user_agent::String,
  scheme::String,
  routing::Dictionary(address::String),
  …
)

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

HELLO {user_agent::String, scheme::String, principal::String, credentials::String, routing::Dictionary(address::String))

Example 1:

HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001"}}

Example 2:

HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001", "policy": "example_policy_routing_context", "region": "example_region_routing_context"}}

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages. Servers can include metadata that describes details of the server environment and/or the connection.

The following fields are defined for inclusion in the SUCCESS metadata.

The new hints dictionary may contain a set of optional configuration hints which may be interpreted or ignored by drivers at their own discretion in order to augment operations where applicable. A full listing of the available hints may be found in Appendix B. Hints remain valid throughout the lifetime of a given connection and cannot be changed. As such, newly established connections may observe different hints and/or hint values as the server configuration is adjusted.

Example:

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

Server Response FAILURE

A FAILURE message response indicates that the client is not permitted to exchange further messages. Servers may choose to include metadata describing the nature of the failure but must immediately close the connection after the failure has been sent.

Example:

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

Request Message - 4.3 - ROUTE

The ROUTE instructs the server to return the current routing table. In previous versions there was no explicit message for this and a procedure had to be invoked using Cypher through the RUN and PULL messages.

This message can only be sent after successful authentication and outside of transactions.

Signature: 66

Fields:

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

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

ROUTE {routing} [bookmarks] "db"

Example 1:

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

Example 2:

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

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages.

The following fields are defined for inclusion in the SUCCESS metadata.

Example:

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

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Version 4.4

Deltas

The changes compared to Bolt protocol version 4.4 are listed below:

Messages - 4.4

Message Signature Request Message Summary Message Detail Message Fields Description
HELLO 01 x     extra::Dictionary(user_agent::String, scheme::String, routing::Dictionary(address::String)) initialize connection
GOODBYE 02 x       close the connection, triggers a <DISCONNECT> signal
RESET 0F x       reset the connection, triggers a <INTERRUPT> signal
RUN 10 x     query::String, parameters::Dictionary, extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String, imp_user::String) execute a query
DISCARD 2F x     extra::Dictionary(n::Integer, qid::Integer) discard records
PULL 3F x     extra::Dictionary(n::Integer, qid::Integer) fetch records
BEGIN 11 x     extra::Dictionary(bookmarks::List<String>, tx_timeout::Integer, tx_metadata::Dictionary, mode::String, db::String, imp_user::String) begin a new transaction
COMMIT 12 x       commit a transaction
ROLLBACK 13 x       rollback a transaction
ROUTE 66 x     routing::Dictionary(address::String), bookmarks::List<String>, extra::Dictionary(db::String, imp_user::String) fetch the current routing table
SUCCESS 70   x   metadata::Dictionary request succeeded
IGNORED 7E   x     request was ignored
FAILURE 7F   x   metadata::Dictionary(code::String, message::String) request failed
RECORD 71     x data::List data values

Request Message - 4.4 - HELLO

The HELLO message requests the connection to be authorized for use with the remote database.

The server must be in the CONNECTED state to be able to process a HELLO message. For any other states, receipt of an HELLO request must be considered a protocol violation and lead to connection closure.

Clients should send HELLO message to the server immediately after connection and process the corresponding response before using that connection in any other way.

If authentication fails, the server must respond with a FAILURE message and immediately close the connection.

Clients wishing to retry initialization should establish a new connection.

Signature: 01

Fields:

extra::Dictionary(
  user_agent::String,
  scheme::String,
  routing::Dictionary(address::String),
  …
)

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

HELLO {user_agent::String, scheme::String, principal::String, credentials::String, routing::Dictionary(address::String))

Example 1:

HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001"}}

Example 2:

HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001", "policy": "example_policy_routing_context", "region": "example_region_routing_context"}}

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages. Servers can include metadata that describes details of the server environment and/or the connection.

The following fields are defined for inclusion in the SUCCESS metadata.

The new hints dictionary may contain a set of optional configuration hints which may be interpreted or ignored by drivers at their own discretion in order to augment operations where applicable. A full listing of the available hints may be found in Appendix B. Hints remain valid throughout the lifetime of a given connection and cannot be changed. As such, newly established connections may observe different hints and/or hint values as the server configuration is adjusted.

Example:

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

Server Response FAILURE

A FAILURE message response indicates that the client is not permitted to exchange further messages. Servers may choose to include metadata describing the nature of the failure but must immediately close the connection after the failure has been sent.

Example:

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

Request Message - RUN - 4.4

The RUN message requests that a Cypher query is executed with a set of parameters and additional extra data.

This message could both be used in an Explicit Transaction or an Auto-commit Transaction. The transaction type is implied by the order of message sequence.

Signature: 10

Fields:

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

An Explicit Transaction (BEGIN+RUN) does not carry any data in the extra field.

For Auto-commit Transaction (RUN) the extra field carries:

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

RUN "query" {parameters} {extra}

Example 1:

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

Example 2:

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

Example 3:

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

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages.

The following fields are defined for inclusion in the SUCCESS metadata.

For Explicit Transaction (BEGIN+RUN):

Example 1:

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

Example 2:

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

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - BEGIN - 4.4

The BEGIN message request the creation of a new Explicit Transaction.

This message should then be followed by a RUN message.

The Explicit Transaction is closed with either the COMMIT message or ROLLBACK message.

Signature: 11

Fields:

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

Detail Messages:

No detail messages.

Valid Summary Messages:

Synopsis

BEGIN {extra}

Example 1:

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

Example 2:

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

Server Response SUCCESS

Example:

SUCCESS {}

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Request Message - 4.4 - ROUTE

The ROUTE instructs the server to return the current routing table. In previous versions there was no explicit message for this and a procedure had to be invoked using Cypher through the RUN and PULL messages.

This message can only be sent after successful authentication and outside of transactions.

Signature: 66

Fields:

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

Detail Messages:

No detail messages should be returned.

Valid Summary Messages:

Synopsis

ROUTE {routing} [bookmarks] {extra}

Example 1:

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

Example 2:

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"}

Server Response SUCCESS

A SUCCESS message response indicates that the client is permitted to exchange further messages.

The following fields are defined for inclusion in the SUCCESS metadata.

Example:

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"}]}
}

Server Response IGNORED

Example:

IGNORED

Server Response FAILURE

Example:

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

Appendix A - Bolt Message Exchange Examples

Example 1

C: 60 60 B0 17
C: 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 00
S: 00 00 00 04
C: HELLO {"user_agent": "Example/4.0.0", "scheme": "basic", "principal": "user", "credentials": "password"}
S: SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "example-connection-id:1"}
C: GOODBYE

Example 2

C: 60 60 B0 17
C: 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 00
S: 00 00 00 04
C: HELLO {"user_agent": "Example/4.0.0", "scheme": "basic", "principal": "user", "credentials": "password"}
S: SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "example-connection-id:1"}
C: RUN "RETURN $x AS example" {"x": 123} {"mode": "r", "db": "example_database"}
S: SUCCESS {"fields": ["example"]}
C: PULL {"n": -1}
S: RECORD [123]
S: SUCCESS {"bookmark": "example-bookmark:1", "t_last": 300, "type": "r", "db": "example_database"}
C: GOODBYE

Example 3

C: 60 60 B0 17
C: 00 00 01 04 00 00 00 00 00 00 00 00 00 00 00 00
S: 00 00 01 04
C: HELLO {"user_agent": "Example/4.1.0", "scheme": "basic", "principal": "user", "credentials": "password", "routing": {"address": "x.example.com:9001", "policy": "example_policy_routing_context", "region": "example_region_routing_context"}}
S: SUCCESS {"server": "Neo4j/4.1.0", "connection_id": "example-connection-id:1"}
C: RUN "RETURN $x AS example" {"x": 123} {"mode": "r", "db": "example_database"}
S: SUCCESS {"fields": ["example"]}
C: PULL {"n": -1}
S: RECORD [123]
S: SUCCESS {"bookmark": "example-bookmark:1", "t_last": 300, "type": "r", "db": "example_database"}
C: GOODBYE

Example 4

C: 60 60 B0 17
C: 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 00
S: 00 00 00 04
C: HELLO {"user_agent": "Example/4.0.0", "scheme": "basic", "principal": "test", "credentials": "test"}
S: SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "example-connection-id:1"}
C: BEGIN {"mode": "r", "db": "example_database", "tx_metadata": {"foo": "bar"}, "tx_timeout": 300}
S: SUCCESS {}
C: RUN "UNWIND [1,2,3,4] AS x RETURN x" {} {}
S: SUCCESS {"fields": ["x"], "qid": 0}
C: PULL {"n": 2}
S: RECORD [1]
S: RECORD [2]
S: SUCCESS {"has_more": true}
C: DISCARD {"n": -1, "qid": 0}
S: SUCCESS {"type": "r", "db": "test"}
C: COMMIT
S: SUCCESS {"bookmark": "neo4j:bookmark-test-1"}

Appendix B - Connection Hints

As of version 4.3, the server may optionally include a set of configuration hints within the SUCCESS metadata provided in response to the HELLO message. Drivers may choose to interpret or ignore these hints at their own discretion. The following set of hints are currently defined:

connection.recv_timeout_seconds - 4.3

Maximum amount of time (in seconds) for which a connection may remain idle following a request before drivers should consider it stale.

The server will ensure that a chunk (or NOOP chunk) will be transmitted at least once per timeout period. Drivers which choose to interpret this hint may terminate connections which are considered stale by the definition of this hint.

Example
C: HELLO {"user_agent": "Example/4.0.0", "scheme": "basic", "principal": "test", "credentials": "test"}
S: SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "example-connection-id:1", "hints": {"connection.recv_timeout_seconds": 120}}