StatementRunner (Neo4j Java Driver 1.7.3 API)

All Known Subinterfaces:

Session, Transaction
```
public interface StatementRunner
```
Common interface for components that can execute Neo4j statements.
Important notes on semantics
Statements run in the same StatementRunner are guaranteed to execute in order, meaning changes made by one statement will be seen by all subsequent statements in the same StatementRunner. However, to allow handling very large results, and to improve performance, result streams are retrieved lazily from the network. This means that when any of the blocking run(Statement) or async runAsync(Statement) methods return a result, the statement 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 statements to complete at specific points to fulfill its contracts. Specifically, the driver will ensure all outstanding statements are completed whenever you:
- Read from or discard a result, for instance via blocking StatementResult.next(), StatementResult.consume() or async StatementResultCursor.nextAsync(), StatementResultCursor.consumeAsync()
- Explicitly commit/rollback a transaction using blocking Transaction.close() or async Transaction.commitAsync(), Transaction.rollbackAsync()
- Close a session using blocking Session.close() or async Session.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 Session.close(). 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(Statement) execute queries in async fashion and return CompletionStage of a new StatementResultCursor. 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 run(String) on the returned stage. Driver will throw IllegalStateException when blocking API call is executed in IO thread. 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:

1.0

See Also:

Session, Transaction

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`StatementResult`	`run(Statement statement)` Run a statement and return a result stream.
`StatementResult`	`run(String statementTemplate)` Run a statement and return a result stream.
`StatementResult`	`run(String statementTemplate, Map<String,Object> statementParameters)` Run a statement and return a result stream.
`StatementResult`	`run(String statementTemplate, Record statementParameters)` Run a statement and return a result stream.
`StatementResult`	`run(String statementTemplate, Value parameters)` Run a statement and return a result stream.
`CompletionStage<StatementResultCursor>`	`runAsync(Statement statement)` Run a statement asynchronously and return a `CompletionStage` with a result cursor.
`CompletionStage<StatementResultCursor>`	`runAsync(String statementTemplate)` Run a statement asynchronously and return a `CompletionStage` with a result cursor.
`CompletionStage<StatementResultCursor>`	`runAsync(String statementTemplate, Map<String,Object> statementParameters)` Run a statement asynchronously and return a `CompletionStage` with a result cursor.
`CompletionStage<StatementResultCursor>`	`runAsync(String statementTemplate, Record statementParameters)` Run a statement asynchronously and return a `CompletionStage` with a result cursor.
`CompletionStage<StatementResultCursor>`	`runAsync(String statementTemplate, Value parameters)` Run a statement asynchronously and return a `CompletionStage` with a result cursor.
`TypeSystem`	`typeSystem()`

- Method Detail
  - run
```
StatementResult run(String statementTemplate,
                    Value parameters)
```
    Run a statement and return a result stream. This method takes a set of parameters that will be injected into the statement 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, run(String, Map) might be more helpful, it converts your map to a Value for you.
    Example
```
 StatementResult cursor = session.run( "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
                                       Values.parameters( "myNameParam", "Bob" ) );
 
 
```
    Parameters:
    
    statementTemplate - text of a Neo4j statement
    
    parameters - input parameters, should be a map Value, see Values.parameters(Object...).
    
    Returns:
    
    a stream of result values and associated metadata
  - runAsync
```
CompletionStage<StatementResultCursor> runAsync(String statementTemplate,
                                                Value parameters)
```
    Run a statement asynchronously and return a CompletionStage with a result cursor.
    This method takes a set of parameters that will be injected into the statement 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<StatementResultCursor> 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:
    
    statementTemplate - text of a Neo4j statement
    
    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.
  - run
```
StatementResult run(String statementTemplate,
                    Map<String,Object> statementParameters)
```
    Run a statement and return a result stream. This method takes a set of parameters that will be injected into the statement 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 run 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");

 StatementResult cursor = session.run( "MATCH (n) WHERE n.name = {myNameParam} RETURN (n)",
                                       parameters );
 
 
```
    Parameters:
    
    statementTemplate - text of a Neo4j statement
    
    statementParameters - input data for the statement
    
    Returns:
    
    a stream of result values and associated metadata
  - runAsync
```
CompletionStage<StatementResultCursor> runAsync(String statementTemplate,
                                                Map<String,Object> statementParameters)
```
    Run a statement asynchronously and return a CompletionStage with a result cursor.
    This method takes a set of parameters that will be injected into the statement 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<StatementResultCursor> 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:
    
    statementTemplate - text of a Neo4j statement
    
    statementParameters - input data for the statement
    
    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.
  - run
```
StatementResult run(String statementTemplate,
                    Record statementParameters)
```
    Run a statement and return a result stream. This method takes a set of parameters that will be injected into the statement 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 run takes a Record of parameters, which can be useful if you want to use the output of one statement as input for another.
    
    Parameters:
    
    statementTemplate - text of a Neo4j statement
    
    statementParameters - input data for the statement
    
    Returns:
    
    a stream of result values and associated metadata
  - runAsync
```
CompletionStage<StatementResultCursor> runAsync(String statementTemplate,
                                                Record statementParameters)
```
    Run a statement asynchronously and return a CompletionStage with a result cursor.
    This method takes a set of parameters that will be injected into the statement 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 statement as input for another.
    It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.
    
    Parameters:
    
    statementTemplate - text of a Neo4j statement
    
    statementParameters - input data for the statement
    
    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.
  - run
```
StatementResult run(String statementTemplate)
```
    Run a statement and return a result stream.
    
    Parameters:
    
    statementTemplate - text of a Neo4j statement
    
    Returns:
    
    a stream of result values and associated metadata
  - runAsync
```
CompletionStage<StatementResultCursor> runAsync(String statementTemplate)
```
    Run a statement 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:
    
    statementTemplate - text of a Neo4j statement
    
    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.
  - run
```
StatementResult run(Statement statement)
```
    Run a statement and return a result stream.
    Example
```
 Statement statement = new Statement( "MATCH (n) WHERE n.name=$myNameParam RETURN n.age" );
 StatementResult cursor = session.run( statement.withParameters( Values.parameters( "myNameParam", "Bob" )  ) );
 
 
```
    Parameters:
    
    statement - a Neo4j statement
    
    Returns:
    
    a stream of result values and associated metadata
  - runAsync
```
CompletionStage<StatementResultCursor> runAsync(Statement statement)
```
    Run a statement asynchronously and return a CompletionStage with a result cursor.
    Example
```
 
 Statement statement = new Statement( "MATCH (n) WHERE n.name=$myNameParam RETURN n.age" );
 CompletionStage<StatementResultCursor> cursorStage = session.runAsync(statement);
 
 
```
    It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc for more information.
    Parameters:
    
    statement - a Neo4j statement
    
    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.
  - typeSystem
```
@Experimental
TypeSystem typeSystem()
```
    Returns:
    
    type system used by this statement runner for classifying values

Interface StatementRunner

Important notes on semantics

Asynchronous API

Method Summary

Method Detail

run

Example

runAsync

Example

run

Example

runAsync

Example

run

runAsync

run

runAsync

run

Example

runAsync

Example

typeSystem