Sessions and Transactions

Sessions

Through the Driver, we open Sessions.

A session is a container for a sequence of transactions. Sessions borrow connections from a pool as required and are considered lightweight and disposable.

It is important to remember that sessions are not the same as database connections. When the Driver connects to the database, it opens up multiple TCP connections that can be borrowed by the session. A query may be sent over multiple connections, and results may be received by the driver over multiple connections.

Instead, sessions should be considered a client-side abstraction for grouping units of work, which also handle the underlying connections. The connections themselves are managed internally by the driver and are not directly exposed to the application.

To open a new session, call the AsyncSession() method on the driver.

c#
Open a new Session
// Open a new session
var session = driver.AsyncSession();

The Session method takes an optional configuration argument, which can be used to set the database to run any queries against in a multi-database setup, and the default access mode for any queries run within the transaction (either READ or WRITE).

c#
Open a new Session with additional arguments
// Create a Session for the `people` database
using var session = driver.AsyncSession(configBuilder =>
    configBuilder
        .WithDefaultAccessMode(AccessMode.Write)
        .WithDatabase("people"));

If no database is supplied, the default database will be used. This is configured in the dbms.default_database in neo4j.conf, the default value is neo4j. You cannot create multiple databases in Neo4j Aura or in Neo4j Community Edition.

The default access mode is set to WRITE, but this can be overwritten by explicitly calling the ExecuteReadAsync() or ExecuteWriteAsync() methods.

Transactions

Through a Session, we can run one or more Transactions.

A transaction comprises a unit of work performed against a database. It is treated in a coherent and reliable way, independent of other transactions.

ACID Transactions

A transaction, by definition, must be

  • atomic,

  • consistent,

  • isolated, and

  • durable.

Many developers are familiar with ACID transactions from their work with relational databases, and as such the ACID consistency model has been the norm for some time.

There are three types of transaction exposed by the driver:

  • Auto-commit Transactions

  • Read Transactions

  • Write Transactions

Auto-commit Transactions

Auto-commit transactions are a single unit of work that are immediately executed against the DBMS and acknowledged immediately. You can run an auto-commit transaction by calling the RunAsync() method on the session object, passing in a Cypher statement as a string and optionally an object containing a set of parameters.

c#
var query = "MATCH () RETURN count(*) AS count";
var queryParams = new Dictionary<string, object>();

// Run a query in an auto-commit transaction
var cursor = await session.RunAsync(query, queryParams);
var record = await cursor.SingleAsync();
var result = record["count"].As<long>();

For one-off queries only

In the event that there are any transient errors when running a query, the driver will not attempt to retry a query when using session.RunAsync(). For this reason, these should only be used for one-off queries and shouldn’t be used in production with Neo4j clusters.

Read Transactions

When you intend to read data from Neo4j, you should execute a Read Transaction. In a clustered environment (including Neo4j AuraDB), read queries are distributed across the database cluster.

The session provides an ExecuteReadAsync() method, which expects a single parameter, a callback function that represents the unit of work. The function will accept a single parameter, a Transaction object, on which you can call the tx.RunAsync() method with two arguments: the Cypher statement as a string and an optional set of query parameters.

c#
Running a Read Transaction
// Run a query within a Read Transaction
var res = await session.ExecuteReadAsync(async tx => {
    var cursor = await tx.RunAsync(@"
        MATCH(p: Person) -[:ACTED_IN]->(m: Movie)
        WHERE m.title = $title // (1)
        RETURN p.name AS name
        LIMIT 10
    ", new { title = "Arthur" });

    var records = await cursor.ToListAsync();
    return records.Select(x => x["name"].As<string>());
});

Parameterized Queries

In the query above, the $ prefix of $title (1) indicates that this value relates to the parameter defined in the second argument (2) of the RunAsync() method call.

You do not need to explicitly commit a read transaction. If anything goes wrong within of the unit of work or there is a problem on Neo4j’s side, the transaction will be automatically rolled back and the database will remain in its previous state. If the unit of work succeeds, the transaction will be automatically committed.

Additionally, unlike session.RunAsync(), if a transient error is received by the driver, for example a connectivity issue with the DBMS, the driver will automatically retry the unit of work.

Write Transactions

If you intend to write data to the database, you should execute a Write Transaction.

If anything goes wrong within of the unit of work or there is a problem on Neo4j’s side, the transaction will be automatically rolled back and the database will remain in its previous state. If the unit of work succeeds, the transaction will be automatically committed and the changes applied and synchronized.

In clustered environments, write queries are sent exclusively to the leader of the cluster. The leader of the cluster is then responsible for processing the query and synchronising the transaction across a write-quorum of the followers and eventually read-replica servers in the cluster.

c#
Running a Write Transaction
await session.ExecuteWriteAsync(async tx =>
{
    var cursor = await tx.RunAsync(
        "CREATE (p:Person {name: $name})",
        new {name = "Michael"});
    await cursor.ConsumeAsync();
});

Manually Creating Transactions

It is also possible to explicitly create a transaction object by calling the BeginTransactionAsync() method on the session.

c#
Creating an Manual Transaction
// Open a new session
using var session = driver.AsyncSession(configBuilder =>
{
    configBuilder.WithDefaultAccessMode(AccessMode.Write);
});
// Manually create a transaction
var tx = await session.BeginTransactionAsync();

This returns a Transaction object identical to the one passed in to the unit of work function when calling ExecuteReadAsync() or ExecuteWriteAsync().

This method differs from the ExecuteReadAsync and ExecuteWriteAsync() methods, in that the transaction will have to be manually committed or rolled back depending on the outcome of the unit of work.

You can commit a transaction by calling the tx.CommitAsync() method, or roll back the transaction by calling tx.RollbackAsync().

c#
try
{
    // Perform an action
    await tx.RunAsync(query);

    // Commit the transaction
    await tx.CommitAsync();
}
catch (Exception)
{
    // If something went wrong, rollback the transaction
    await tx.RollbackAsync();
}

Closing the Session

When you are finished interacting with Neo4j, you will need to call the CloseAsync() method to release any resources held by the session.

c#
Closing a Session
// Close the session
await session.CloseAsync();

A Working Example

Click to reveal a complete working example

The following code defines a method that accepts a name parameter, then executes a write transaction to create a :Person node in the people database.

c#
Create a Person node in the customers database
private async Task<Dictionary<string, object>> CreatePerson(IDriver driver, string name)
{
    // Create a Session for the `people` database
    using var session = driver.AsyncSession(configBuilder =>
        configBuilder
            .WithDefaultAccessMode(AccessMode.Write)
            .WithDatabase("people"));

    // Create a node within a write transaction
    var result = await session.ExecuteWriteAsync(async tx =>
    {
        var cursor = await tx.RunAsync("CREATE (p:Person {name: $name}) RETURN p",
            new {name});
        return await cursor.SingleAsync();
    });

    // Get the `p` value from the first record
    var node = result["p"].As<INode>();

    // Return the properties of the node
    return node.Properties
        .ToDictionary(x => x.Key, x => x.Value);
}

Check your understanding

1. Valid Query Methods

Which of the following options are valid methods for running a read query through the driver?

  • session.Run()

  • session.RunAsync()

  • session.Read()

  • session.ExecuteReadAsync()

Hint

You can either run a Cypher statement within an auto-commit transaction or execute a Cypher statement within a managed transaction.

Solution

The answers are session.RunAsync() and session.ExecuteReadAsync().

2. Reading from the Database

Say we want to create a new transaction that reads. We want any queries from this method to be distributed across the cluster.

Use the dropdown in the code block below to select the correct method.

c#
var cursor = await session./*select:readMethod*/(tx -> {
    // Use tx.RunAsync to read from the database
})
  • ❏ ReadAsync

  • ❏ ReadQueryAsync

  • ✓ ExecuteReadAsync

  • ❏ ExecuteWriteAsync

Hint

You are looking to execute a read query against the database.

Solution

The answer is ExecuteReadAsync

3. Writing to the Database

Now we want to create a new node in the database.

Use the dropdown in the code block below to select the correct method.

c#
var res = session./*select:writeMethod*/(tx -> {
    // Use tx.RunAsync to write to the database
})
  • ❏ Insert

  • ❏ WriteAsync

  • ❏ WriteQuery

  • ✓ ExecuteWriteAsync

Hint

You are looking to execute a read query against the database.

Solution

The answer is ExecuteWriteAsync

Lesson Summary

In this lesson, you have learned about the process of creating sessions and running Cypher queries within transaction functions.

In the next lesson we will look at how we process the results of a query.