Module org.neo4j.driver
Package org.neo4j.driver

Interface ExecutableQuery

public interface ExecutableQuery
An executable query that executes a query in a managed transaction with automatic retries on retryable errors.

This is a high-level API for executing a query. There are more advanced APIs available. For instance, Session, Transaction and transaction functions that are accessible via methods like Session.executeWrite(TransactionCallback), Session.executeWriteWithoutResult(Consumer) and Session.executeRead(TransactionCallback) (there are also overloaded options available).

Causal consistency is managed via driver's BookmarkManager that is enabled by default. It is possible to use a different BookmarkManager or disable it via QueryConfig.Builder.withBookmarkManager(BookmarkManager) on individual basis.

Sample usage: 

 
 var eagerResult = driver.executableQuery("CREATE (n{field: $value}) RETURN n")
         .withParameters(Map.of("value", "5"))
         .execute();
The above sample is functionally similar to the following use of the more advanced APIs: 
 
 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());
     });
 }
In addition, it is possible to transform query result by using a supplied Collector implementation.

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.executableQuery("UNWIND range(0, 5) as N RETURN N")
         .execute(averagingLong(record -> record.get("N").asLong()));

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

 var maxValue = driver.executableQuery("UNWIND range(0, 5) as N RETURN N")
         .execute(mapping(record -> record.get("N").asLong(), maxBy(Long::compare)));
If there is a need to access Result.keys() and/or ResultSummary value, 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.executableQuery("UNWIND range(0, 5) as N RETURN N")
                     .execute(Collectors.mapping(record -> record.get("N").asLong(), toSet()), ResultValue::new);
Since:
5.7

  • Method Details

    • withParameters

      ExecutableQuery withParameters(Map<String,Object> parameters)
      Sets query parameters.
      Parameters:
      parameters - parameters map, must not be null
      Returns:
      a new executable query

    • withConfig

      ExecutableQuery withConfig(QueryConfig config)
      Sets QueryConfig.

      By default, ExecutableQuery has QueryConfig.defaultConfig() value.

      Parameters:
      config - query config, must not be null
      Returns:
      a new executable query

    • withAuthToken

      default ExecutableQuery withAuthToken(AuthToken authToken)
      Sets an AuthToken to be used for this query.

      The default value is null.

      The minimum Bolt protocol version for this feature is 5.1. An UnsupportedFeatureException will be emitted on query execution for previous Bolt versions.

      Parameters:
      authToken - the AuthToken for this query or null to use the driver default
      Returns:
      a new executable query
      Since:
      5.18

    • execute

      default EagerResult execute()
      Executes query, collects all results eagerly and returns a result.
      Returns:
      an instance of result containing all records, keys and result summary

    • execute

      default <T> T execute(Collector<Record,?,T> recordCollector)
      Executes query, collects Record values using the provided Collector and produces a final result.
      Type Parameters:
      T - the final result type
      Parameters:
      recordCollector - collector instance responsible for processing Record values and producing a collected result, the collector may be used multiple times if query is retried
      Returns:
      the final result value

    • execute

      <A, R, T> T execute(Collector<Record,A,R> recordCollector, ExecutableQuery.ResultFinisher<R,T> resultFinisher)
      Executes query, collects Record values using the provided Collector and produces a final result by invoking the provided BiFunction with the collected result and ResultSummary values.

      If any of the arguments throws an exception implementing the RetryableException marker interface, the query is retried automatically in the same way as in the transaction functions. Exceptions not implementing the interface trigger transaction rollback and are then propagated to the user.

      Type Parameters:
      A - the mutable accumulation type of the collector's reduction operation
      R - the collector's result type
      T - the final result type
      Parameters:
      recordCollector - collector instance responsible for processing Record values and producing a collected result, the collector may be used multiple times if query is retried
      resultFinisher - function accepting the Result.keys(), collected result and ResultSummary values to output the final result value, the function may be invoked multiple times if query is retried
      Returns:
      the final result value