Neo4j Transaction Size: Batch for Performance (2026)

Neo4j transaction size is a critical lever for performance, and the common wisdom to "batch your writes" is only part of the story.

Let’s see it in action. Imagine you have a list of users and their friendships to import. A naive approach might be to create a new transaction for each user and their friendships.

// Naive, per-user transaction
for (User user : users) {
    try (Transaction tx = session.beginTransaction()) {
        Node userNode = tx.createNode("User");
        userNode.setProperty("userId", user.getId());
        userNode.setProperty("name", user.getName());

        for (Friendship friendship : user.getFriendships()) {
            Node friendNode = tx.findNode(Label.label("User"), "userId", friendship.getFriendId());
            if (friendNode == null) {
                // Handle case where friend doesn't exist yet - could be its own transaction or skipped
                continue;
            }
            userNode.createRelationshipTo(friendNode, RelationshipType.withName("FRIENDS_WITH"));
        }
        tx.commit();
    }
}

This creates thousands of individual transactions, each with its own overhead: ACID guarantees, locking, and network round trips. The database spends more time managing transactions than actually writing data.

The "batching" solution looks like this:

// Batched transaction
try (Transaction tx = session.beginTransaction()) {
    for (User user : users) {
        Node userNode = tx.createNode("User");
        userNode.setProperty("userId", user.getId());
        userNode.setProperty("name", user.getName());

        for (Friendship friendship : user.getFriendships()) {
            Node friendNode = tx.findNode(Label.label("User"), "userId", friendship.getFriendId());
            if (friendNode == null) {
                continue;
            }
            userNode.createRelationshipTo(friendNode, RelationshipType.withName("FRIENDS_WITH"));
        }
    }
    tx.commit();
}

This single transaction performs all the work. The overhead is amortized across all operations, leading to significantly higher throughput. But what’s the optimal size?

The problem Neo4j solves is managing complex, interconnected data efficiently. Traditional relational databases struggle with deep relationships, often requiring expensive JOINs. Neo4j’s graph model, with nodes and relationships, makes traversing these connections incredibly fast. The Transaction object in the Neo4j driver is the unit of work. It ensures that a set of operations either all succeed or all fail, maintaining data integrity. When you call tx.commit(), Neo4j performs a series of internal steps: it acquires locks, writes data to memory, flushes it to disk (via the page cache and transaction logs), and then makes the changes visible. Each commit incurs this overhead.

Here’s where it gets interesting: Neo4j has internal limits and optimizations related to transaction size. While you can put millions of operations into a single transaction, you’ll eventually hit memory limits or performance degradation due to lock contention and the sheer volume of data being processed within one atomic unit. The driver also has configurable limits, like maxTransactions for BatchGraphDatabase (though this is more for explicit batching utilities) or internal buffer sizes. The sweet spot is often found through empirical testing, but a common range for bulk imports is between 1,000 and 100,000 operations per transaction. Too small, and you have excessive transaction overhead. Too large, and you risk out-of-memory errors or long-running transactions that block other operations.

The specific limits are often tied to Neo4j’s internal memory management, particularly the page cache and the transaction log buffer. When a transaction grows too large, it can strain these resources. For instance, if a transaction modifies a vast number of pages in the cache, it might lead to increased I/O as older pages are evicted to make room, even though the transaction itself hasn’t committed yet. Furthermore, the transaction log, which records all changes before they are durably written, can also grow to an unmanageable size, impacting recovery times and potentially causing disk space issues if not managed properly. Neo4j’s architecture is designed for efficient writes, but extremely large transactions can push beyond these optimizations and expose underlying resource constraints.

The next concept to explore is how to handle concurrent writes and reads when using large transactions, and the implications for read consistency.