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
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
A function accepting theResult.keys()
, collected result andResultSummary
values to produce a final result value. -
Method Summary
Modifier and TypeMethodDescriptiondefault EagerResult
execute()
Executes query, collects all results eagerly and returns a result.default <T> T
<A,
R, T> T execute
(Collector<Record, A, R> recordCollector, ExecutableQuery.ResultFinisher<R, T> resultFinisher) Executes query, collectsRecord
values using the providedCollector
and produces a final result by invoking the providedBiFunction
with the collected result andResultSummary
values.default ExecutableQuery
withAuthToken
(AuthToken authToken) Sets anAuthToken
to be used for this query.withConfig
(QueryConfig config) SetsQueryConfig
.withParameters
(Map<String, Object> parameters) Sets query parameters.
-
Method Details
-
withParameters
Sets query parameters.- Parameters:
parameters
- parameters map, must not be null- Returns:
- a new executable query
-
withConfig
SetsQueryConfig
.By default,
ExecutableQuery
hasQueryConfig.defaultConfig()
value.- Parameters:
config
- query config, must not be null- Returns:
- a new executable query
-
withAuthToken
Sets anAuthToken
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
- theAuthToken
for this query or null to use the driver default- Returns:
- a new executable query
- Since:
- 5.18
-
execute
Executes query, collects all results eagerly and returns a result.- Returns:
- an instance of result containing all records, keys and result summary
-
execute
- Type Parameters:
T
- the final result type- Parameters:
recordCollector
- collector instance responsible for processingRecord
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 executeT> (Collector<Record, A, R> recordCollector, ExecutableQuery.ResultFinisher<R, T> resultFinisher) Executes query, collectsRecord
values using the providedCollector
and produces a final result by invoking the providedBiFunction
with the collected result andResultSummary
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 operationR
- the collector's result typeT
- the final result type- Parameters:
recordCollector
- collector instance responsible for processingRecord
values and producing a collected result, the collector may be used multiple times if query is retriedresultFinisher
- function accepting theResult.keys()
, collected result andResultSummary
values to output the final result value, the function may be invoked multiple times if query is retried- Returns:
- the final result value
-