public interface Session extends Resource, QueryRunner
A Session is a logical container for a causally chained series of
transactions. Client applications typically work
with managed transactions, which come in two flavours: transaction
functions and auto-commit transactions. Managed transactions automatically
handle the transaction boundaries (BEGIN and
COMMIT/ROLLBACK) and can also provide other
supporting features; transaction functions offer retry capabilities, for
example.
Unmanaged transactions are also available but tend to be used by libraries or tooling that require more fine-grained control.
Typically, a session will acquire a TCP connection from a connection pool in order to carry out a transaction. Once the transaction has completed, and the entire result has been consumed, this connection will be released back into the pool. One connection can therefore be adopted by several sessions over its lifetime, although it will only be owned by one at a time. Client applications should never need to deal directly with connection management.
Session implementations are not generally thread-safe. Therefore, multiple sessions should be used when an application requires multiple concurrent threads of database work to be carried out.
AsyncSession in 4.0)| Modifier and Type | Method and Description |
|---|---|
Transaction |
beginTransaction()
Begin a new unmanaged transaction.
|
Transaction |
beginTransaction(TransactionConfig config)
Begin a new unmanaged transaction with
the specified
configuration. |
void |
close()
Signal that you are done using this session.
|
Bookmark |
lastBookmark()
Return the bookmark received following the last completed
transaction.
|
<T> T |
readTransaction(TransactionWork<T> work)
Execute a unit of work in a managed
read transaction. |
<T> T |
readTransaction(TransactionWork<T> work,
TransactionConfig config)
Execute a unit of work in a managed
read transaction
with the specified configuration. |
void |
reset()
Deprecated.
This method should not be used and violates the expected usage pattern of
Session objects.
They are expected to be not thread-safe and should not be shared between thread. However this method is only
useful when Session object is passed to another monitoring thread that calls it when appropriate.
It is not useful when Session is used in a single thread because in this case close()
can be used. Since version 3.1, Neo4j database allows users to specify maximum transaction execution time and
contains procedures to list and terminate running queries. These functions should be used instead of calling
this method. |
Result |
run(Query query,
TransactionConfig config)
Run a query in a managed auto-commit transaction with the specified
configuration, and return a result stream. |
Result |
run(String query,
Map<String,Object> parameters,
TransactionConfig config)
Run a query with parameters in a managed auto-commit transaction with the
specified
configuration, and return a result stream. |
Result |
run(String query,
TransactionConfig config)
Run a query in a managed auto-commit transaction with the specified
configuration, and return a result stream. |
<T> T |
writeTransaction(TransactionWork<T> work)
Execute a unit of work in a managed
write transaction. |
<T> T |
writeTransaction(TransactionWork<T> work,
TransactionConfig config)
Execute a unit of work in a managed
write transaction
with the specified configuration. |
Transaction beginTransaction()
TransactionTransaction beginTransaction(TransactionConfig config)
configuration. At most one
transaction may exist in a session at any point in time. To maintain
multiple concurrent transactions, use multiple concurrent sessions.config - configuration for the new transaction.Transaction<T> T readTransaction(TransactionWork<T> work)
read transaction.
This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
Managed transactions should not generally be explicitly committed (via
Transaction.commit()).
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new read transaction.<T> T readTransaction(TransactionWork<T> work, TransactionConfig config)
read transaction
with the specified configuration.
This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
Managed transactions should not generally be explicitly committed (via
Transaction.commit()).
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new read transaction.config - configuration for all transactions started to execute the unit of work.<T> T writeTransaction(TransactionWork<T> work)
write transaction.
This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
Managed transactions should not generally be explicitly committed (via
Transaction.commit()).
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new write transaction.<T> T writeTransaction(TransactionWork<T> work, TransactionConfig config)
write transaction
with the specified configuration.
This transaction will automatically be committed unless an exception is thrown during query execution or by the user code.
Managed transactions should not generally be explicitly committed (via
Transaction.commit()).
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new write transaction.config - configuration for all transactions started to execute the unit of work.Result run(String query, TransactionConfig config)
configuration, and return a result stream.query - text of a Neo4j query.config - configuration for the new transaction.Result run(String query, Map<String,Object> parameters, TransactionConfig config)
configuration, and return a result stream.
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 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.
Map<String, Object> metadata = new HashMap<>();
metadata.put("type", "update name");
TransactionConfig config = TransactionConfig.builder()
.withTimeout(Duration.ofSeconds(3))
.withMetadata(metadata)
.build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("myNameParam", "Bob");
Result result = session.run("MATCH (n) WHERE n.name = $myNameParam RETURN (n)", parameters, config);
query - text of a Neo4j query.parameters - input data for the query.config - configuration for the new transaction.Result run(Query query, TransactionConfig config)
configuration, and return a result stream.
Map<String, Object> metadata = new HashMap<>();
metadata.put("type", "update name");
TransactionConfig config = TransactionConfig.builder()
.withTimeout(Duration.ofSeconds(3))
.withMetadata(metadata)
.build();
Query query = new Query("MATCH (n) WHERE n.name = $myNameParam RETURN n.age");
Result result = session.run(query.withParameters(Values.parameters("myNameParam", "Bob")));
query - a Neo4j query.config - configuration for the new transaction.Bookmark lastBookmark()
@Deprecated void reset()
Session objects.
They are expected to be not thread-safe and should not be shared between thread. However this method is only
useful when Session object is passed to another monitoring thread that calls it when appropriate.
It is not useful when Session is used in a single thread because in this case close()
can be used. Since version 3.1, Neo4j database allows users to specify maximum transaction execution time and
contains procedures to list and terminate running queries. These functions should be used instead of calling
this method.void close()
close in interface AutoCloseable