org.neo4j.driver.async

Interface AsyncQueryRunner

All Known Subinterfaces:

AsyncSession, AsyncTransaction

public interface AsyncQueryRunner

Asynchronous interface for components that can execute Neo4j queries.

Important notes on semantics

Queries run in the same AsyncQueryRunner are guaranteed to execute in order, meaning changes made by one query will be seen by all subsequent queries in the same AsyncQueryRunner.

However, to allow handling very large results, and to improve performance, result streams are retrieved lazily from the network. This means that when async runAsync(Query) methods return a result, the query has only started executing - it may not have completed yet. Most of the time, you will not notice this, because the driver automatically waits for queries to complete at specific points to fulfill its contracts.

Specifically, the driver will ensure all outstanding queries are completed whenever you:

• Read from or discard a result, for instance via ResultCursor.nextAsync(), ResultCursor.consumeAsync()
• Explicitly commit/rollback a transaction using AsyncTransaction.commitAsync(), AsyncTransaction.rollbackAsync()
• Close a session using AsyncSession.closeAsync()

As noted, most of the time, you will not need to consider this - your writes will always be durably stored as long as you either use the results, explicitly commit transactions or close the session you used using AsyncSession.closeAsync().

While these semantics introduce some complexity, it gives the driver the ability to handle infinite result streams (like subscribing to events), significantly lowers the memory overhead for your application and improves performance.

Asynchronous API

All overloads of runAsync(Query) execute queries in async fashion and return CompletionStage of a new ResultCursor. Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.

Note: Returned stage can be completed by an IO thread which should never block. Otherwise IO operations on this and potentially other network connections might deadlock. Please do not chain blocking operations like CompletableFuture.get() on the returned stage. Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor. This can be done using methods with "Async" suffix like CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).

Since:

4.0

See Also:

AsyncSession, AsyncTransaction

Method Summary

Modifier and Type	Method and Description
CompletionStage<ResultCursor>	runAsync(Query query) Run a query asynchronously and return a CompletionStage with a result cursor.
CompletionStage<ResultCursor>	runAsync(String query) Run a query asynchronously and return a CompletionStage with a result cursor.
CompletionStage<ResultCursor>	runAsync(String query, Map<String,Object> parameters) Run a query asynchronously and return a CompletionStage with a result cursor.
CompletionStage<ResultCursor>	runAsync(String query, Record parameters) Run a query asynchronously and return a CompletionStage with a result cursor.
CompletionStage<ResultCursor>	runAsync(String query, Value parameters) Run a query asynchronously and return a CompletionStage with a result cursor.

Method Detail

runAsync

CompletionStage<ResultCursor> runAsync(String query,
                                       Value parameters)

Run a query asynchronously and return a CompletionStage with a result cursor.

This method takes a set of parameters that will be injected into the query by Neo4j. Using parameters is highly encouraged, it helps avoid dangerous cypher injection attacks and improves database performance as Neo4j can re-use query plans more often.

This particular method takes a Value as its input. This is useful if you want to take a map-like value that you've gotten from a prior result and send it back as parameters.

If you are creating parameters programmatically, runAsync(String, Map) might be more helpful, it converts your map to a Value for you.

Example

 

 CompletionStage<ResultCursor> cursorStage = session.runAsync(
             "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
             Values.parameters("myNameParam", "Bob"));
 
 

It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.

Parameters:

query - text of a Neo4j query

parameters - input parameters, should be a map Value, see Values.parameters(Object...).

Returns:

new CompletionStage that gets completed with a result cursor when query execution is successful. Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.

runAsync

CompletionStage<ResultCursor> runAsync(String query,
                                       Map<String,Object> parameters)

Run a query asynchronously and return a CompletionStage with a result cursor.

This method takes a set of parameters that will be injected into the query by Neo4j. Using parameters is highly encouraged, it helps avoid dangerous cypher injection attacks and improves database performance as Neo4j can re-use query plans more often.

This version of runAsync takes a Map of parameters. The values in the map must be values that can be converted to Neo4j types. See Values.parameters(Object...) for a list of allowed types.

Example

 

 Map<String, Object> parameters = new HashMap<String, Object>();
 parameters.put("myNameParam", "Bob");

 CompletionStage<ResultCursor> cursorStage = session.runAsync(
             "MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
             parameters);
 
 

It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.

Parameters:

query - text of a Neo4j query

parameters - input data for the query

Returns:

new CompletionStage that gets completed with a result cursor when query execution is successful. Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.

runAsync

CompletionStage<ResultCursor> runAsync(String query,
                                       Record parameters)

Run a query asynchronously and return a CompletionStage with a result cursor.

This method takes a set of parameters that will be injected into the query by Neo4j. Using parameters is highly encouraged, it helps avoid dangerous cypher injection attacks and improves database performance as Neo4j can re-use query plans more often.

This version of runAsync takes a Record of parameters, which can be useful if you want to use the output of one query as input for another.

It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.

Parameters:

query - text of a Neo4j query

parameters - input data for the query

Returns:

new CompletionStage that gets completed with a result cursor when query execution is successful. Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.

runAsync

CompletionStage<ResultCursor> runAsync(String query)

Run a query asynchronously and return a CompletionStage with a result cursor.

It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.

Parameters:

query - text of a Neo4j query

Returns:

new CompletionStage that gets completed with a result cursor when query execution is successful. Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.

runAsync

CompletionStage<ResultCursor> runAsync(Query query)

Run a query asynchronously and return a CompletionStage with a result cursor.

Example

 
 Query query = new Query( "MATCH (n) WHERE n.name = $myNameParam RETURN n.age" );
 CompletionStage<ResultCursor> cursorStage = session.runAsync(query);
 
 

It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.

Parameters:

query - a Neo4j query

Returns:

new CompletionStage that gets completed with a result cursor when query execution is successful. Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.