Sessions and Transactions

Sessions

Through the Driver, we open Sessions.

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.

// 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).

// 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.

There are three types of transaction exposed by the driver:

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>();

// 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>());
});

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.

// 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().

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.

// Close the session
await session.CloseAsync();

A Working Example

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