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

Interface Session

All Superinterfaces:
AutoCloseable, BaseSession, QueryRunner, Resource, SimpleQueryRunner
public interface Session extends BaseSession, Resource, QueryRunner
Provides a context of work for database interactions.

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.

Since:
1.0 (Removed async API to AsyncSession in 4.0)

  • Method Details

    • beginTransaction

      Transaction beginTransaction()
      Begin a new unmanaged transaction. At most one transaction may exist in a session at any point in time. To maintain multiple concurrent transactions, use multiple concurrent sessions.
      Returns:
      a new Transaction

    • beginTransaction

      Transaction beginTransaction(TransactionConfig config)
      Begin a new unmanaged transaction with the specified configuration. At most one transaction may exist in a session at any point in time. To maintain multiple concurrent transactions, use multiple concurrent sessions.
      Parameters:
      config - configuration for the new transaction.
      Returns:
      a new Transaction

    • readTransaction

      @Deprecated <T> T readTransaction(TransactionWork<T> work)
      Deprecated.
      superseded by executeRead(TransactionCallback).
      Execute a unit of work in a managed 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 be explicitly committed (via Transaction.commit()).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      work - the TransactionWork to be applied to a new read transaction.
      Returns:
      a result as returned by the given unit of work.

    • executeRead

      default <T> T executeRead(TransactionCallback<T> callback)
      Execute a unit of work as a single, managed transaction with read access mode and retry behaviour. The transaction allows for one or more statements to be run.

      The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.

      The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      Returns:
      a result as returned by the given unit of work.

    • readTransaction

      @Deprecated <T> T readTransaction(TransactionWork<T> work, TransactionConfig config)
      Deprecated.
      superseded by executeRead(TransactionCallback, TransactionConfig).
      Execute a unit of work in a managed 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 be explicitly committed (via Transaction.commit()).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      work - the TransactionWork to be applied to a new read transaction.
      config - configuration for all transactions started to execute the unit of work.
      Returns:
      a result as returned by the given unit of work.

    • executeRead

      <T> T executeRead(TransactionCallback<T> callback, TransactionConfig config)
      Execute a unit of work as a single, managed transaction with read access mode and retry behaviour. The transaction allows for one or more statements to be run.

      The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.

      The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      config - the transaction configuration for the managed transaction.
      Returns:
      a result as returned by the given unit of work.

    • writeTransaction

      @Deprecated <T> T writeTransaction(TransactionWork<T> work)
      Deprecated.
      superseded by executeWrite(TransactionCallback).
      Execute a unit of work in a managed 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 be explicitly committed (via Transaction.commit()).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      work - the TransactionWork to be applied to a new write transaction.
      Returns:
      a result as returned by the given unit of work.

    • executeWrite

      default <T> T executeWrite(TransactionCallback<T> callback)
      Execute a unit of work as a single, managed transaction with write access mode and retry behaviour. The transaction allows for one or more statements to be run.

      The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.

      The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      Returns:
      a result as returned by the given unit of work.

    • executeWriteWithoutResult

      default void executeWriteWithoutResult(Consumer<TransactionContext> contextConsumer)
      Execute a unit of work as a single, managed transaction with write access mode and retry behaviour. The transaction allows for one or more statements to be run.

      The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt.

      This method works equivalently to executeWrite(TransactionCallback), but does not have a return value.

      Parameters:
      contextConsumer - the consumer representing the unit of work.

    • writeTransaction

      @Deprecated <T> T writeTransaction(TransactionWork<T> work, TransactionConfig config)
      Deprecated.
      superseded by executeWrite(TransactionCallback, TransactionConfig).
      Execute a unit of work in a managed 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 be explicitly committed (via Transaction.commit()).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      work - the TransactionWork to be applied to a new write transaction.
      config - configuration for all transactions started to execute the unit of work.
      Returns:
      a result as returned by the given unit of work.

    • executeWrite

      <T> T executeWrite(TransactionCallback<T> callback, TransactionConfig config)
      Execute a unit of work as a single, managed transaction with write access mode and retry behaviour. The transaction allows for one or more statements to be run.

      The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.

      The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      config - the transaction configuration for the managed transaction.
      Returns:
      a result as returned by the given unit of work.

    • executeWriteWithoutResult

      default void executeWriteWithoutResult(Consumer<TransactionContext> contextConsumer, TransactionConfig config)
      Execute a unit of work as a single, managed transaction with write access mode and retry behaviour. The transaction allows for one or more statements to be run.

      The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.

      This method works equivalently to executeWrite(TransactionCallback, TransactionConfig), but does not have a return value.

      Parameters:
      contextConsumer - the consumer representing the unit of work.
      config - the transaction configuration for the managed transaction.

    • run

      Result run(String query, TransactionConfig config)
      Run a query in a managed auto-commit transaction with the specified configuration, and return a result stream.
      Parameters:
      query - text of a Neo4j query.
      config - configuration for the new transaction.
      Returns:
      a stream of result values and associated metadata.

    • run

      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.

      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.

      Example

       
 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);
      Parameters:
      query - text of a Neo4j query.
      parameters - input data for the query.
      config - configuration for the new transaction.
      Returns:
      a stream of result values and associated metadata.

    • run

      Result run(Query query, TransactionConfig config)
      Run a query in a managed auto-commit transaction with the specified configuration, and return a result stream.

      Example

       
 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")));
      Parameters:
      query - a Neo4j query.
      config - configuration for the new transaction.
      Returns:
      a stream of result values and associated metadata.

    • lastBookmark

      @Deprecated Bookmark lastBookmark()
      Deprecated.
      Return the last bookmark of this session.

      When no new bookmark is received, the initial bookmarks are returned as a composite Bookmark containing all initial bookmarks. This may happen when no work has been done using the session. If no initial bookmarks have been provided, an empty Bookmark is returned.

      Returns:
      the last bookmark.

    • lastBookmarks

      Set<Bookmark> lastBookmarks()
      Return a set of last bookmarks.

      When no new bookmark is received, the initial bookmarks are returned. This may happen when no work has been done using the session. Multivalued Bookmark instances will be mapped to distinct Bookmark instances. If no initial bookmarks have been provided, an empty set is returned.

      Returns:
      the immutable set of last bookmarks.

    • close

      void close()
      Signal that you are done using this session. In the default driver usage, closing and accessing sessions is very low cost.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Resource