diff --git a/modules/ROOT/pages/bolt-compatibility.adoc b/modules/ROOT/pages/bolt-compatibility.adoc index 3f450b6..5037f07 100644 --- a/modules/ROOT/pages/bolt-compatibility.adoc +++ b/modules/ROOT/pages/bolt-compatibility.adoc @@ -2,6 +2,22 @@ = Bolt Protocol and Neo4j compatibility +:fn-version-plus: pass:c,q[footnote:calver[" - current" includes all newer versions until further notice (inclduing newer major versions). \ +At some point, the server might drop support for older Bolt versions, but there's no plan or guarantee for when or if that will happen. \ +As soon as a decision is made, it will be documented here.]] + +== Bolt 6.x + +[cols="^,^",options="header"] +|=== +| Neo4j version +| Bolt `6.0` + +| `2025.10` - current{fn-version-plus} +| `x` + +|=== + == Bolt 5.x [cols="^,^,^,^,^,^,^,^,^,^",options="header"] @@ -85,7 +101,7 @@ | | -| `5.26`+ +| `5.26` - current{fn-version-plus} | `x` | `x` | `x` @@ -98,6 +114,7 @@ |=== +[NOTE] Bolt version 5.5 is not used, and no Neo4j server will ever negotiate it. == Bolt 4.x @@ -141,14 +158,7 @@ Bolt version 5.5 is not used, and no Neo4j server will ever negotiate it. | `x` | -| `4.4` -| `(x)` -| `(x)` -| `(x)` -| `(x)` -| `x` - -| `5.0`+ +| `4.4` - current{fn-version-plus} | `(x)` | `(x)` | `(x)` diff --git a/modules/ROOT/pages/bolt/message.adoc b/modules/ROOT/pages/bolt/message.adoc index 86153ac..a208bf3 100644 --- a/modules/ROOT/pages/bolt/message.adoc +++ b/modules/ROOT/pages/bolt/message.adoc @@ -2052,7 +2052,10 @@ metadata::Dictionary The following fields are defined in the metadata: -* `message::String` - the human readable description of the failure. +* `message::String` - The description of the failure, for debugging or display purposes. +Since Bolt 6.0, there is no guarantee that the format or the message associated to a specific failure will stay stable. +Changes to error messages are not classified as breaking changes. For a stable marker of an error, use `gql_status`. +label:changed[Changed in bolt 6.0] * `code::String` - the neo4j code identifying the failure. label:deprecated[Removed after bolt 5.6] * `neo4j_code::String` - the neo4j code identifying the failure. @@ -2130,6 +2133,11 @@ RECORD [{"point": [1, 2]}, "example_data", 123] The sections below list the changes of messages compared to the previous version. Please also check for changes in xref:./structure-semantics.adoc#structure-summary[Structure Semantics]. +[[messages-summary-6]] +=== Version 6.0 + +** `FAILURE` message -- Field `message` has no guarantee that the format or the message associated to a specific failure will stay stable. + [[messages-summary-58]] === Version 5.8 @@ -2153,7 +2161,7 @@ Please also check for changes in xref:./structure-semantics.adoc#structure-summa [[messages-summary-55]] === Version 5.5 [WARNING] -.Unsupported (and undocumented 😏) protocol version +.Unsupported (and undocumented 😏️) protocol version ==== Version 5.5 was only ever released in some drivers, but has a flawed design. No Neo4j server will negotiate this protocol version. @@ -2182,7 +2190,7 @@ No Neo4j server will negotiate this protocol version. ** `LOGOFF` message has been added. [[messages-summary-5]] -=== Version 5 +=== Version 5.0 ** No changes from version 4.4 diff --git a/modules/ROOT/pages/bolt/structure-semantics.adoc b/modules/ROOT/pages/bolt/structure-semantics.adoc index 46a97a8..3fcdaee 100644 --- a/modules/ROOT/pages/bolt/structure-semantics.adoc +++ b/modules/ROOT/pages/bolt/structure-semantics.adoc @@ -67,6 +67,14 @@ The table below lists the PackStream specified structures and their code and tag | `Y` | `59` +| <> +| `V` +| `56` + +| <> +| `?` +| `3F` + 3+| *Legacy Structures* | <> @@ -83,7 +91,7 @@ The table below lists the PackStream specified structures and their code and tag A snapshot of a node within a graph database. -_The `element_id` field was added with version *5.0* and does not exist in earlier versions._ +The `element_id` field was added with version *5.0* and does not exist in earlier versions. label:new[Introduced in bolt 5.0] *tag byte:* `4E` @@ -116,7 +124,7 @@ B4 4E A snapshot of a relationship within a graph database. -_The fields `element_id`, `start_node_element_id`, and `end_node_element_id` were added with version *5.0* and do not exist in earlier versions._ +The fields `element_id`, `start_node_element_id`, and `end_node_element_id` were added with version *5.0* and do not exist in earlier versions. label:new[Introduced in bolt 5.0] *tag byte:* `52` @@ -158,7 +166,7 @@ B8 52 A relationship without start or end node ID. It is used internally for Path serialization. -_The `element_id` field was added with version *5.0* and does not exist in earlier versions._ +The `element_id` field was added with version *5.0* and does not exist in earlier versions. label:new[Introduced in bolt 5.0] *tag byte:* `72` @@ -239,6 +247,7 @@ Date::Structure( Where the `days` are days since https://en.wikipedia.org/wiki/Epoch_(computing)[Unix epoch]. `0` for example represents 1970-01-01 while `1` represents 1970-01-02. + [[structure-time]] === `Time` @@ -273,8 +282,10 @@ LocalTime::Structure( Where the `nanoseconds` are nanoseconds since midnight. + [[structure-datetime]] === `DateTime` +label:new[Introduced in bolt 5.0] An instant capturing the date, the time, and the time zone. The time zone information is specified with a zone offset. @@ -319,9 +330,12 @@ The deserialization of such a `DateTime` structure expectedly happens in reverse - instantiate the idiomatic equivalent of `DateTime` based on that Unix timestamp (`4500` seconds and `42` nanoseconds), giving `1970-01-01T01:15:00.000000042Z` - localize the resulting UTC `DateTime` to the timezone of the specified offset, giving `1970-01-01T02:15:00.000000042+0100` + [[structure-datetimezoneid]] === `DateTimeZoneId` +label:new[Introduced in bolt 5.0] + An instant capturing the date, the time, and the time zone. The time zone information is specified with a zone identifier. @@ -421,6 +435,7 @@ Duration::Structure( ) ---- + [[structure-point2d]] === `Point2D` @@ -439,6 +454,7 @@ Point2D::Structure( Where the `srid` is a _Spatial Reference System Identifier_. + [[structure-point3d]] === `Point3D` @@ -458,10 +474,65 @@ Point3D::Structure( Where the `srid` is a _Spatial Reference System Identifier_. + +[[structure-vector]] +=== `Vector` +label:new[Introduced in bolt 6.0] + +An ordered collection of homogeneous types. + +*tag byte:* `56` + +*Number of fields:* 2 +---- +Vector::Structure( + type_marker::Bytes, + data::Bytes, +) +---- + +* `type_marker` specifies the inner type of the vector: +** `C8` for `8-bit signed integer` +** `C9` for `16-bit signed integer` (in big-endian order) +** `CA` for `32-bit signed integer` (in big-endian order) +** `CB` for `64-bit signed integer` (in big-endian order) +** `C6` for `32-bit floating point value` (IEEE-754 single precision representation in big-endian order) +** `C1` for `64-bit floating point value` (IEEE-754 double precision representation in big-endian order) +* `data` is a sequence of values encoded as specified in `type_marker` (the marker is not repeated in `data`). + + +[[structure-unsupported-type]] +=== `UnsupportedType` +label:new[Introduced in bolt 6.0] + +A placeholder value for the server to represent a value of a type not supported by the currently negotiated protocol version. + +*tag byte:* `3F` + +*Number of fields:* 4 +---- +UnsupportedType::Structure( + name::String, + minimum_protocol_major::Integer, + minimum_protocol_minor::Integer, + extra::Dictionary { + message::String, + }, +) +---- + +* `name` is the name of the type that could not be transmitted (e.g, `"QuantumFloat"`). +* `minimum_protocol_major` is the minimum major protocol version required to transmit this type (e.g., `42` if 42.21 is required protocol version). +* `minimum_protocol_minor` is the minimum minor protocol version required to transmit this type (e.g., `21` if 42.21 is required protocol version). +* `extra` contains additional information +** `message` is an optional, human-readable message that may contain additional information, e.g., a migration path or required configuration options. + + == Legacy Structures [[structure-legacy-datetime]] === `Legacy DateTime` +label:deprecated[Removed after bolt 4.4] An instant capturing the date, the time, and the time zone. The time zone information is specified with a zone offset. @@ -509,6 +580,7 @@ The deserialization of such a `DateTime` structure expectedly happens in reverse [[structure-legacy-datetimezoneid]] === `Legacy DateTimeZoneId` +label:deprecated[Removed after bolt 4.4] An instant capturing the date, the time, and the time zone. The time zone information is specified with a zone identifier. @@ -589,6 +661,11 @@ Since `DateTimeZoneId` does not include the timezone offset, the resolution of t The sections below list the changes of structure semantics in versions where they changed. Please also check for changes in xref:./message.adoc#messages-summary[Bolt Messages]. +[[structure-summary-6]] +=== Version 6.0 +** The <> structure was added. +** The <> structure was added. + [[structure-summary-5]] === Version 5.0