 |
VOOZH | about |
|
VOOZH | about |
This document covers the modern Bolt protocol versions V5.x (5.0 through 5.8) and V6, which introduce significant architectural changes to authentication, graph structure identification, and numeric data transmission. These versions represent the current state of the Bolt protocol as of Neo4j 2025.x.
For foundational protocol concepts, see Protocol V1 and V2 - Foundation. For transaction support, see Protocol V3 - Transaction Support. For streaming and routing features, see Protocol V4.x Series - Streaming and Routing.
The V5 series represents a significant evolution in the Bolt protocol, introducing breaking changes to authentication flow and graph structure identification. Each minor version (5.0 through 5.8) adds incremental improvements while maintaining backward compatibility within the series.
| Version | Neo4j Version | Key Feature |
|---|---|---|
| V5.0 | 5.0+ | element_id in Node/Relationship structures |
| V5.1 | 5.5+ | Separated HELLO/LOGON authentication flow |
| V5.2 | 5.7+ | Enhanced routing metadata |
| V5.3 | 5.9+ | Bolt agent tracking in HELLO |
| V5.4 | 5.13+ | TELEMETRY message for API usage tracking |
| V5.5-V5.8 | 5.x+ | Minor protocol refinements |
Sources: tests/TestLayer.php69-109 src/protocol/V5_2.php1-34
Prior to V5.1, authentication credentials were passed directly in the HELLO message, creating a single-step authentication process:
V5.1 introduces a separated authentication flow with distinct HELLO, LOGON, and LOGOFF messages, enabling connection reuse with different authentication contexts:
Sources: src/protocol/v5_1/HelloMessage.php1-28 src/protocol/v5_1/LogonMessage.php1-23 src/protocol/v5_1/LogoffMessage.php1-23
The V5.1+ authentication flow is implemented through three trait-based message classes:
src/protocol/v5_1/HelloMessage.php17-27 - Initiates connection without authentication:
Parameters:
user_agent: Client identification string (defaults to "bolt-php")routing: Optional routing context for cluster deploymentssrc/protocol/v5_1/LogonMessage.php17-22 - Authenticates the connection:
Message signature: 0x6A
Authentication dictionary keys:
scheme: Authentication scheme ("basic", "kerberos", etc.)principal: Usernamecredentials: Password or tokensrc/protocol/v5_1/LogoffMessage.php17-22 - Deauthenticates while maintaining connection:
Message signature: 0x6B
Sources: src/protocol/v5_1/HelloMessage.php1-28 src/protocol/v5_1/LogonMessage.php1-23 src/protocol/v5_1/LogoffMessage.php1-23 tests/protocol/V5_1Test.php27-112
The V5.1+ authentication flow introduces a new AUTHENTICATION state between NEGOTIATION and READY:
Sources: src/protocol/v5_1/ServerStateTransition.php tests/protocol/V5_1Test.php41-43 tests/protocol/V5_1Test.php72-78 tests/protocol/V5_1Test.php104-106
V5.0 introduces element_id as a string-based identifier for graph entities (Node, Relationship, UnboundRelationship), replacing the integer-only id field used in previous versions. This change supports composite databases and advanced clustering architectures.
id field remains for legacy clientsThe V5 structures maintain both id (integer) and element_id (string) fields:
Node Structure (V5):
0x4Eid (int), element_id (string), labels (array), properties (dictionary)Relationship Structure (V5):
0x52id (int), element_id (string), startNodeId (int), startNodeElementId (string), endNodeId (int), endNodeElementId (string), type (string), properties (dictionary)UnboundRelationship Structure (V5):
0x72id (int), element_id (string), type (string), properties (dictionary)Applications should prefer element_id over id when working with V5+ protocols.
Sources: src/protocol/v5/structures/Node.php src/protocol/v5/structures/Relationship.php src/protocol/v5/structures/UnboundRelationship.php
Protocol V6 (Neo4j 2025.10+) introduces the Vector structure for efficient transmission of numeric arrays, optimizing memory usage and network bandwidth for machine learning and graph analytics use cases.
Sources: src/protocol/v6/structures/Vector.php18-29 src/protocol/v6/structures/TypeMarker.php1-21
src/protocol/v6/structures/TypeMarker.php12-20 defines six data type markers for vector encoding:
| TypeMarker | Hex Value | Data Type | Range |
|---|---|---|---|
INT_8 | 0xC8 | 8-bit signed integer | -128 to 127 |
INT_16 | 0xC9 | 16-bit signed integer | -32,768 to 32,767 |
INT_32 | 0xCA | 32-bit signed integer | -2,147,483,648 to 2,147,483,647 |
INT_64 | 0xCB | 64-bit signed integer | Full 64-bit range |
FLOAT_32 | 0xC6 | 32-bit IEEE 754 float | ±3.4e38 (7 digits precision) |
FLOAT_64 | 0xC1 | 64-bit IEEE 754 float | ±1.7e308 (15 digits precision) |
Sources: src/protocol/v6/structures/TypeMarker.php12-20
The Vector::encode() method src/protocol/v6/structures/Vector.php40-87 converts PHP arrays to binary vector format:
Key implementation details:
s, l, q formats on little-endian systemsc: signed char (INT_8)s: signed short, big-endian (INT_16)l: signed long, big-endian (INT_32)q: signed long long, big-endian (INT_64)G: float, big-endian (FLOAT_32)E: double, big-endian (FLOAT_64)Sources: src/protocol/v6/structures/Vector.php40-108
The Vector::decode() method src/protocol/v6/structures/Vector.php115-153 converts binary vector data back to PHP arrays:
Sources: src/protocol/v6/structures/Vector.php115-153
From the V6 structure tests tests/structures/V6/StructuresTest.php41-104:
Unpacking vectors from Neo4j:
Packing vectors to Neo4j:
Forcing specific type:
Sources: tests/structures/V6/StructuresTest.php41-104
src/protocol/v6/AvailableStructures.php34-62 registers Vector in both packer and unpacker structure lookup tables:
This enables automatic serialization/deserialization when Vector objects are passed as query parameters or received in results.
Sources: src/protocol/v6/AvailableStructures.php34-62 src/packstream/v1/Packer.php212-231 src/packstream/v1/Unpacker.php123-156
| Feature | V3/V4 | V5.0 | V5.1+ | V6 |
|---|---|---|---|---|
| Authentication | HELLO (one-step) | HELLO (one-step) | HELLO → LOGON (two-step) | HELLO → LOGON (two-step) |
| Graph Entity ID | id (int only) | id + element_id (string) | id + element_id (string) | id + element_id (string) |
| User Switching | Reconnect required | Reconnect required | LOGOFF → LOGON | LOGOFF → LOGON |
| AUTHENTICATION State | No | No | Yes | Yes |
| Vector Structure | No | No | No | Yes (0x56) |
| TELEMETRY Message | No | No | V5.4+ | Yes |
| Bolt Agent Tracking | No | No | V5.3+ | Yes |
Sources: src/protocol/V5_2.php1-34 src/protocol/V6.php1-37
Each V5.x version extends AProtocol and composes features via traits:
V5_2 Class Structure src/protocol/V5_2.php13-34:
Trait composition strategy:
element_id)Sources: src/protocol/V5_2.php13-34
V6 Class Structure src/protocol/V6.php13-37:
Key differences from V5.x:
v6\AvailableStructures which includes Vector (0x56)v5_3\HelloMessage with Bolt agent trackingv5_4\TelemetryMessage for API usage metricsSources: src/protocol/V6.php13-37
Protocol tests verify message construction and state transitions without requiring a live database connection:
V5_1 Authentication Tests tests/protocol/V5_1Test.php27-49:
V6 Vector Integration Tests tests/structures/V6/StructuresTest.php41-104:
Sources: tests/protocol/V5_1Test.php17-112 tests/structures/V6/StructuresTest.php41-104
tests/TestLayer.php37-60 provides unified authentication across all protocol versions:
This method detects protocol version capabilities and uses appropriate authentication flow, demonstrating the practical differences between V3/V4, V5.1+, and legacy versions.
Sources: tests/TestLayer.php37-60
Protocol V5.x and V6 represent the modern Bolt protocol specification with three major architectural improvements:
element_id string identifiers enable advanced clustering and federated database architecturesThese versions maintain backward compatibility through trait composition while introducing breaking changes to authentication flow that require client-side adaptation.
Refresh this wiki