Bolt (network protocol)
Original author(s) | Neo Technology |
---|---|
Stable release |
Version 1
|
Development status | Active |
Written in | Various languages |
Operating system | Any |
Platform | Cross-platform |
Type | Network protocol |
License | Creative Commons 3.0 Attribution-ShareAlike |
Website |
boltprotocol |
The Bolt Protocol (Bolt) is a connection oriented network protocol used for client-server communication in database applications. It operates over a TCP connection or WebSocket.
Bolt is statement-oriented, allowing a client to send messages containing a statement consisting of a single string and a set of typed parameters. The server responds to each statement with a result message and an optional stream of result records.
Developed for use in the Neo4j graph database, Bolt was heavily inspired by the binary network protocol of PostgreSQL and features a data interchange format derived from MessagePack. The protocol is published on the website http://boltprotocol.org.
Versioning
The protocol supports explicit versioning and version negotiation between the client and the server. There is only one published version of the protocol: version 1.
Protocol Overview - Version 1
Messaging
Bolt clients and servers both send data over the connection as a sequence of messages. Each message has a type (denoted by a "signature" byte) and may include additional data. The client drives the interaction, and each message sent by the client will cause one or more response messages to be sent by the server.
Client messages:
Type | Signature |
---|---|
INIT | 0x01[1] |
RUN | 0x10[2] |
DISCARD_ALL | 0x2F[3] |
PULL_ALL | 0x3F[4] |
ACK_FAILURE | 0x0E[5] |
RESET | 0x0F[6] |
Server messages:
Type | Signature |
---|---|
SUCCESS | 0x70[7] |
FAILURE | 0x7F[8] |
IGNORED | 0x7E[9] |
RECORD | 0x71[10] |
Message Transfer Encoding
Each message is encoded into a sequence of bytes. These bytes are transferred using a binary chunked encoding, where each chunk is preceded by an unsigned, big-endian 16-bit integer denoting the number of bytes that immediately follow. A length of 0 is used to denote the end of the message.
Failure Handling
A client may send multiple messages to a server, without first waiting for a response.[11] The server processes each message sequentially. However, as there may be logical dependencies between messages sent by the client, the server will not evaluate requests it receives after sending FAILURE in response to a preceding message. Instead, it will send an IGNORED message in reply to every client message, until the client acknowledges the failure by sending an ACK_FAILURE message.
This is similar to the failure handling and recovery in the PostgreSQL wire protocol.
Data Encoding
Bolt supports encoding for a number of different data types.
Type | Description |
---|---|
Null [12] | Represents the absence of a value. |
Boolean [13] | Boolean true or false. |
Integer [14] | 64-bit signed integer. |
Float [15] | 64-bit floating point number. |
String [16] | UTF-8 encoded string. |
List [17] | Ordered collection of values. |
Map [18] | Unordered, keyed collection of values. |
Node [19] | A node in a Property Graph with optional properties and labels. |
Relationship [20] | A directed, typed connection between two nodes in a Property Graph. Each relationship may have properties and always has an identity. |
Path [21] | The record of a directed walk through a Property Graph, consisting of a sequence of zero or more segments. |
References
- ↑ Bolt version 1 INIT message
- ↑ Bolt version 1 RUN message
- ↑ Bolt version 1 DISCARD_ALL message
- ↑ Bolt version 1 PULL_ALL message
- ↑ Bolt version 1 ACK_FAILURE message
- ↑ Bolt version 1 RESET message
- ↑ Bolt version 1 SUCCESS message
- ↑ Bolt version 1 FAILURE message
- ↑ Bolt version 1 IGNORED message
- ↑ Bolt version 1 RECORD message
- ↑ Bolt message pipelining
- ↑ Bolt version 1 Null type
- ↑ Bolt version 1 Boolean types
- ↑ Bolt version 1 Integer types
- ↑ Bolt version 1 Float types
- ↑ Bolt version 1 String types
- ↑ Bolt version 1 List types
- ↑ Bolt version 1 Map types
- ↑ Bolt version 1 Node type
- ↑ Bolt version 1 Relationship type
- ↑ Bolt version 1 Path type