BOLT V3 INFORMATION
Since Neo4j 3.5, boltv3 is here!
Nothing changes regarding types / structures, only messages are impacted.
Metadata
Metadata is a structure used as parameters by RUN and BEGIN. It is the same for both messages.
It purpose is not well defined yet. Needs research...
| Name |
type |
description |
| bookmarks |
list(string) |
A list of bookmarks to be used |
| tx_timeout |
int |
the query timeout (milliseconds) |
| tx_metadata |
map |
? |
HELLO
This message replaces INIT and serves the same purpose.
Required parameters
| Name |
type |
description |
| user_agent |
string |
similar to client_name used in INIT |
| scheme |
string |
|
| credentials |
string |
|
| principal |
string |
|
Example
HELLO %{credentials: "password", principal: "neo4j", scheme: "basic", user_agent: "Boltex/0.5.0"}
Return
SUCCESS
or
FAILURE with an error string
When successfull, return contains the following data
| Name |
type |
description |
| server |
string |
The neo4j server version |
| connection_id |
string |
|
Example
SUCCESS %{"connection_id" => "bolt-31", "server" => "Neo4j/3.5.1"}
RUN (Upated message)
RUN message still exists in bolt v1 and v2 and is used to send a query to the server. The server will respond with an acknowledglement and information about the result. Be aware that the result is not in the result. You have to send a PULL_ALL message to get the result.
Required parameters
| Name |
type |
description |
| _query |
string |
the query to be executed |
| _parameters |
map |
The parameters to be used by query |
| _metadata |
map |
The metadata to be used (see metadata) |
Examples
"RETURN 1 as num" %{} %{}
"MATCH (:Person {uid: {uid}} RETURN p as person" %{uid: 5} %{tx_timeout: 5000}
Return
SUCCESS with data
or
FAILURE with an error string
When successfull, return contains the following data
| Name |
type |
description |
| fields |
list(string) |
fields that will be found in result |
| t_first |
int |
When the result will be available (replaces result_available_after) |
Example
SUCCESS %{"fields" => ["num"], "t_first" => 0}
PULL_ALL (Upated message)
PULL_ALL message still exists in bolt v1 and v2 is used to fetch result from a previous RUN message.
Required parameters
None
Example
PULL_ALL
Return
multiple RECORD messages and a final SUCCESS
or
FAILURE with an error string
First, PULL_ALL will return RECORDs containing the query result.
When this stream is complete, it will return a SUCCESS message containing
| Name |
type |
description |
| bookmark |
string |
A bookmark name |
| stats |
map |
The stats summary (only for write operations) |
| t_last |
int |
time for result consumption (replaces result_consumed_after) |
| type |
string |
The operation type: read or write |
Examples:
# Read
RECORD [1]
SUCCESS %{"bookmark" => "neo4j:bookmark:v1:tx16732", "t_last" => 0, "type" => "r"}
# Write
SUCCESS ~ %{"bookmark" => "neo4j:bookmark:v1:tx16733", "stats" => %{"labels-added" => 1, "nodes-created" => 1, "properties-set" => 2}, "t_last" => 0, "type" => "w"}
BEGIN
Signature: 0x11
BEGIN starts a transaction.
Required parameters
| Name |
type |
description |
| _metadata |
map |
The metadata to be used (see metadata) |
Example
BEGIN %{}
BEGIN %{bookmarks: ["neo4j:bookmark:v1:tx111"]}
Return
SUCCESS message without data
or
FAILURE with an error string
Example
SUCCESS %{}
COMMIT
Signature: 0x12
COMMIT commits the currently open transaction.
Required parameters
None
Example
COMMIT
Return
SUCCESS with data
or
FAILURE with an error string
When successfull, return contains the following data:
| Name |
type |
description |
| bookmark |
string |
A bookmark name |
Example
SUCCESS %{"bookmark" => "neo4j:bookmark:v1:tx16732"}
ROLLBACK
Signature 0x13
ROLLBACK rollbacks the currently open transaction.
Required parameters
None
Example
ROLLBACK
Return
SUCCESS message without data
or
FAILURE with an error string
Example
SUCCESS %{}
GOODBYE
Signature: 0x02
GOODBYE closes the open connection
Required parameters
None
Example
GOODBYE
Return
Nothing because connection is closed. Server doesn't sent anything back!
BOLT V3 INFORMATION
Since Neo4j 3.5, boltv3 is here!
Nothing changes regarding types / structures, only messages are impacted.
Metadata
Metadatais a structure used as parameters byRUNandBEGIN. It is the same for both messages.It purpose is not well defined yet. Needs research...
HELLO
This message replaces
INITand serves the same purpose.Required parameters
INITExample
HELLO %{credentials: "password", principal: "neo4j", scheme: "basic", user_agent: "Boltex/0.5.0"}Return
SUCCESSor
FAILUREwith an error stringWhen successfull, return contains the following data
Example
SUCCESS %{"connection_id" => "bolt-31", "server" => "Neo4j/3.5.1"}RUN (Upated message)
RUNmessage still exists in bolt v1 and v2 and is used to send a query to the server. The server will respond with an acknowledglement and information about the result. Be aware that the result is not in the result. You have to send aPULL_ALLmessage to get the result.Required parameters
Examples
"RETURN 1 as num" %{} %{}"MATCH (:Person {uid: {uid}} RETURN p as person" %{uid: 5} %{tx_timeout: 5000}Return
SUCCESSwith dataor
FAILUREwith an error stringWhen successfull, return contains the following data
result_available_after)Example
SUCCESS %{"fields" => ["num"], "t_first" => 0}PULL_ALL (Upated message)
PULL_ALLmessage still exists in bolt v1 and v2 is used to fetch result from a previousRUNmessage.Required parameters
None
Example
PULL_ALLReturn
multiple
RECORDmessages and a finalSUCCESSor
FAILUREwith an error stringFirst,
PULL_ALLwill returnRECORDs containing the query result.When this stream is complete, it will return a
SUCCESSmessage containingresult_consumed_after)Examples:
BEGIN
Signature: 0x11
BEGINstarts a transaction.Required parameters
Example
BEGIN %{}BEGIN %{bookmarks: ["neo4j:bookmark:v1:tx111"]}Return
SUCCESSmessage without dataor
FAILUREwith an error stringExample
SUCCESS %{}COMMIT
Signature: 0x12
COMMITcommits the currently open transaction.Required parameters
None
Example
COMMITReturn
SUCCESSwith dataor
FAILUREwith an error stringWhen successfull, return contains the following data:
Example
SUCCESS %{"bookmark" => "neo4j:bookmark:v1:tx16732"}ROLLBACK
Signature 0x13
ROLLBACKrollbacks the currently open transaction.Required parameters
None
Example
ROLLBACKReturn
SUCCESSmessage without dataor
FAILUREwith an error stringExample
SUCCESS %{}GOODBYE
Signature: 0x02
GOODBYEcloses the open connectionRequired parameters
None
Example
GOODBYEReturn
Nothing because connection is closed. Server doesn't sent anything back!