v5.5.0 - Feedback wanted on QueryTask

[injectives]

Introduction

Java driver version 5.5.0 introduced a new high-level query execution API. It comes as experimental at this stage, meaning it is subject to more flexible updates than a mature API.

The objective of this API is to provide an opinionated, managed and convenient query execution option. The new API does not require the Result object management and ensures automatic query retries should retryable conditions occur, like a change of leadership in causal cluster. It is not meant to replace nor match all capabilities of lower level APIs.

The new QueryTask class is the central part of this new API. It offers a Fluent style API and is responsible for query setup and managed execution.

Basic usage

The code below illustrates a basis usage of the new API:

 var eagerResult = driver.queryTask("CREATE (n{field: $value}) RETURN n")
         .withParameters(Map.of("value", "5"))
         .execute();

The execute() method returns an object of a new EagerResult class. This new type contains an in-memory result of executing a Cypher query that has been consumed in full. It's interface is presented below:

public interface EagerResult {
    List<String> keys();
    List<Record> records();
    ResultSummary summary();
}

The example above is functionally similar to the following use of the lower-level API:

 var query = new Query("CREATE (n{field: $value}) RETURN n", Map.of("value", "5"));
 var sessionConfig = SessionConfig.builder()
         .withBookmarkManager(driverConfig.queryBookmarkManager())
         .build();
 try (var session = driver.session(sessionConfig)) {
     var eagerResult = session.executeWrite(tx -> {
         var result = tx.run(query);
         return new EagerResultValue(result.keys(), result.stream().toList(), result.consume());
     });
 }

Collector support

In addition to the basic usage, it is possible to collect query Records by using a supplied java.util.stream.Collector implementation. Some implementations are available in the java.util.stream.Collectors class.

It is strongly recommended to use Cypher query language capabilities where possible. The examples below just provide a sample usage of the API.

 import static java.util.stream.Collectors.*;

 var averagingLong = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
         .execute(averagingLong(record -> record.get("N").asLong()));

 var filteredValues = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
         .execute(mapping(record -> record.get("N").asLong(), filtering(value -> value > 2, toList())));

 var maxValue = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
         .execute(mapping(record -> record.get("N").asLong(), maxBy(Long::compare)));

Should access to the Result.keys() and/or ResultSummary values be needed, another method option is available:

 import static java.util.stream.Collectors.*;

 private record ResultValue(List<String> keys, Set<Long> values, ResultSummary summary) {}

 var result = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
                     .execute(Collectors.mapping(record -> record.get("N").asLong(), toSet()), ResultValue::new);

Feedback wanted

It would be great to get some feedback on this new API. Please let us know what you think, this includes API suggestions and even just general comments with usage experience.

[injectives]

This API has been graduated to GA status in the 5.8.0 release.
https://github.com/neo4j/neo4j-java-driver/releases/tag/5.8.0