This release brings news features, general improvements and dependency updates.

The sections below describe the main updates in this release and the full changelog is listed in the end.

Java Driver Manual

6.0 API documentation

Neo4j Vector

Neo4j Vector is a new data type introduced in Neo4j server (2025.10, Enterprise Edition).

The driver's type system has been extended to support it.

A new Vector interface represents Neo4j Vector. At present, it has 6 subtypes:

• Int8Vector - INTEGER8 vector that has Java byte elements and can be converted to byte[] array
• Int16Vector - INTEGER16 vector that has Java short elements and can be converted to short[] array
• Int32Vector - INTEGER32 vector that has Java int elements and can be converted to int[] array
• Int64Vector - INTEGER vector that has Java long elements and can be converted to long[] array
• Float32Vector - FLOAT16 vector that has Java float elements and can be converted to float[] array
• Float64Vector - FLOAT vector that has Java double elements and can be converted to double[] array

Similarly to the IsoDuration, new Value instance containing Vector can be created using one of the provided Values#vector(...) factory methods. The Type of such Value is equal to TypeSystem#VECTOR().

Usage example:

var value = Values.vector(new float[] {0.0f});
var result = driver.executableQuery("CREATE (:VectorTest {vector: $vector})")
        .withParameters(Map.of("vector", value))
        .execute();

Since Vector is a sealed interface, it works well with Pattern Matching for switch:

switch (value.asVector()) {
    case Int8Vector int8Vector -> {
        var arr = int8Vector.toArray();
    }
    case Int16Vector int16Vector -> {
        var arr = int16Vector.toArray();
    }
    case Int32Vector int32Vector -> {
        var arr = int32Vector.toArray();
    }
    case Int64Vector int64Vector -> {
        var arr = int64Vector.toArray();
    }
    case Float32Vector float32Vector -> {
        var arr = float32Vector.toArray();
    }
    case Float64Vector float64Vector -> {
        var arr = float64Vector.toArray();
    }
}

Alongside Value#asVector(), it is also possible to map Value to Vector using the Value#as(Class<T>) method. This is especially useful when Vector subtype is well-known:

var vector = value.as(Float32Vector.class);

It is also possible to map to array directly:

var arr = value.as(float[].class);

When using Object Mapping, it is possible to define record components both as Vector and arrays with Vector annotation:

record DomainRecord(
        Float32Vector float32Vector, 
        @Vector float floatArr) {}
var domainRecord = value.as(DomainRecord.class);

Unsupported Type

The Neo4j Vector is a good example of a new type being introduced to the system. It is possible that at some point the driver version connecting to the server might not support a new future type because it requires a newer protocol version to support it.

A new UnsupportedType object has been introduced to identify such types and provide some information about them, like:

• name
• minimum protocol version
• an optional message

The Type of a Value with UnsupportedType is equal to TypeSystem#UNSUPPORTED().

Usage example:

var unsupportedType = value.asUnsupportedType();
System.out.println(unsupportedType.name());
System.out.println(unsupportedType.minProtocolVersion());
unsupportedType.message().ifPresent(System.out::println);

Sending the UnsupportedType back to the server is not supported.

Bill of Materials (BOM)

A new Maven artifact neo4j-java-driver-bom represents driver's Bill of Materials (BOM).

It is especially useful when additional driver dependencies are used.

Usage example (Maven):

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

The driver BOM also imports netty-bom to ensure compatible versions, especially when Netty Native Transport is used.

Should it be necessary, users can override netty-bom version by importing it before the driver BOM:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.netty</groupId>
            <artifactId>netty-bom</artifactId>
            <version>${netty-bom.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Query API

NOTE: This feature is in preview.

Neo4j Query API is an HTTP API for executing Cypher statements.

The driver supports connecting to this API over HTTP.

The Query API support is enabled by:

• including an extra dependency
• using https or http URI scheme

Example (Maven):

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
    </dependency>
    <dependency>
        <groupId>org.neo4j.bolt</groupId>
        <artifactId>neo4j-bolt-connection-query-api</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <!--> BOM ensures the versions are compatible <-->
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Driver creation example:

var driver = GraphDatabase.driver("https://query.api.local", authToken);

The are some limitations with this integration at the moment. The main unsuported items are listed below:

• Home database resolution.
• Records streaming.
  • All records are loaded ahead of time to client-side memory. If you deal with large datasets, this integration might need more memory.
• Neo4j Vector.
• Unsupported Type.
• Transaction metadata.
• Notification preferences.
• ResultSummary#resultAvailableAfter(TimeUnit).
• ResultSummary#resultConsumedAfter(TimeUnit).
• ResultSummary#queryType().
• ResultSummary#plan().
• ResultSummary#profile().

Since home database resolution is not supported, the database name MUST be set explicitly using the driver API. Alternatively, it is possible to append the default database name to the URI, it will be used when no database name is set explicitly.

Example: https://query.api.local?defaultDatabase=neo4j

<dependency>
    <groupId>org.neo4j.driver</groupId>
    <artifactId>neo4j-java-driver</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.neo4j.bolt</groupId>
            <artifactId>neo4j-bolt-connection-netty</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Unix Domain Socket

bolt+unix URI scheme allows connecting to Neo4j server over Unix Domain Socket.

Example:

try (var driver = GraphDatabase.driver("bolt+unix:///var/run/neo4j.sock")) {
    var result = driver.executableQuery("SHOW DATABASES")
            .withConfig(QueryConfig.builder().withDatabase("system").build())
            .execute();
    result.records().forEach(System.out::println);
}

While the driver does not impose any special limitations on such connections, the server has a dedicated purpose for them - administration. Therefore, it limits interations to system database only. See the server configuration settings.

Netty Native Transport

Using Netty Native Transport may bring better performance and less garbage collection as mentioned in the Netty documentation.

In addition, TFO is only supported with Netty Native Transport.

The native transport support is limited to the following URI schemes:

• neo4j
• bolt

Only the following Maven artifacts are supported:

• netty-transport-native-io_uring (Netty 4.2+ only)
• netty-transport-native-epoll
• netty-transport-native-kqueue

The driver automatically uses Netty Native Transport when it is added to runtime.

Example (Maven):

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
    </dependency>
    <!--> MUST be added manually for a given system <-->
    <dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-transport-native-io_uring</artifactId>
        <classifier>linux-x86_64</classifier>
        <scope>runtime</scope>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <!-- Ensures that the dependency versions are compatible -->
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

TCP Fast Open (TFO)

NOTE: This feature is experimental.

A working TCP Fast Open setup enables the driver to start one of the following during TCP handshake by sending early data:

• Bolt Handshake (for connections not needing encryption)
• TLS Handshake (for connections needing encryption)

The following conditions MUST be met for it to work as expected:

• Netty Native Transport must be used.
• The system the driver is running on MUST:
  • Support TFO.
  • Have it enabled.
• The driver configuration option MUST be enabled.
• The endpoint the driver connects to MUST:
  • Support TFO.
  • Have it enabled both in the system and the Neo4j server.

The driver configuration example:

var config = Config.builder()
        .withTryTcpFastOpen(true)
        .build();

Logging

The driver now uses Java System.Logger by default.

The Logging abstraction has been deprecated for future removal.

Since Java System.Logger uses Java Util Logging (JUL) by default, logging can be adjusted by modifying $JAVA_HOME/conf/loggig.properties file.

There are 2 main root loggers that the driver uses:

• org.neo4j.driver - Driver-level logging.
• org.neo4j.bolt.connection - Bolt-level logging.

For instance, to see driver logging in console:

• Make sure java.util.logging.ConsoleHandler.level is set to the desired logging level.
• Add facility-specific properties with desired logging levels for the root loggers.

Example:

java.util.logging.ConsoleHandler.level = FINE

org.neo4j.driver.level = FINE
org.neo4j.bolt.connection.level = FINE

Both System.Logger and JUL can be bridged to other logging solutions should this be needed.

Observability

NOTE: This feature is in preview.

Observability of the driver has been improved in this release.

A new ObservationProvider type provides an integration point for driver observability. There are 2 new driver modules that implement it:

• neo4j-java-driver-observation-metrics
• neo4j-java-driver-observation-micrometer

The former contains the experimental metrics that the driver used to have previously. They have been moved to this new module.

The latter implements integration with Mictomer Observation API. Micrometer is able to create both metrics and traces providing that the relevant handlers are registered.

See #1682 for more details.

Acquisition timeout

The handling of ConfigBuilder#withConnectionAcquisitionTimeout(long, TimeUnit) has been changed to apply to the whole connection acquisition process. Please see the documentation for more details.

Changelog

Please see the full changelog below.

⭐ New Features

• feat(tfo): add experimental support for TFO #1696
• feat(unix): add support for bolt+unix #1700
• feat(unsupportedType): add support for Bolt Unsupported Type #1691
• feat(observability): add Observation SPI #1682
• feat(vector): Introduce support for Neo4j Vector #1663
• feature(bom): introduce BOM and update to Bolt Connection 4.0.0 #1653
• feat(logging): add support for System.Logger and deprecate Logging #1648

👏 Improvements

• feat(bom): Add netty-bom to neo4j-java-driver-bom #1706
• feat(vector): Make Neo4j Vector GA #1704
• feat(vector): add Value#asVector() #1701
• feat(tfo): update config naming #1699
• test: fix ReactiveResultRecordPublisherVerificationIT #1695
• feat(vector): update naming #1692
• fix(acquisition): avoid infinite connection timeout if there is a limit #1689
• feat(native): add support for Netty native transports #1690
• docs(retries): add a note about implicit transaction #1687
• feat(acquisition): apply acquisition timeout to all steps #1685
• feat(observability): allow setting null provider #1686
• feat(observability): add Javadoc #1684
• fix(object-mapping): try making record components accessible #1681
• docs(retry): mention ExecutableQuery in withMaxTransactionRetyTime #1679
• feat(gql-status-object): add legacy notification fields #1677
• feat(gql-status-object): Introduce GqlNotification #1667
• feat(object-mapping): support mapping types with restricted access #1668
• feat(gql-status-object): make GQL Status Object GA #1669
• feat(gql-error): add GQLSTATUS finders #1671
• feat(gql-error): make GQL Error GA #1673
• fix(retry): make RetryLogic executor threads daemon #1661
• perf(value): optimise value handling for Bolt Connection #1657
• refactor: Fix typo in ErrorMapper.mapAndThrow method #1643
• feat: delete deprecated RxSession #1644
• feat(bookmarks): delete deprecated multi value support in Bookmark #1646
• feat: delete deprecated transaction functions #1647
• feat(session): delete deprecated session methods #1649
• feat(config): delete deprecated TrustStrategy.certFile() #1650
• feat(notification): delete deprecated Notification#severity() #1651
• build: build on Java 21 #1645

🔧 Dependency Management

• build(deps): update dependencies #1705
• build(deps): update dependencies #1694
• build(deps): update dependencies #1683
• build(deps): update dependencies #1680
• build(deps): update Bolt Connection 4.1.0 #1654
• build(deps): Update neo4j-bolt-connection to 3.0.0 #1642
• build(deps): update neo4j-bolt-connection to 6.0.1 #1664
• build(deps): update dependencies #1674