Benchmark Driver-Side Throughput and Separate Database Time from Network/Serialization/Client Time

Learning outcomes

The AtlasMart team reports “Neo4j takes 180 ms” because the HTTP endpoint takes 180 ms. But 25 ms is spent waiting for a concurrency permit, 8 ms acquiring a connection, the server reports results available after 22 ms, 70 ms is spent consuming/serializing 2 MB, and the rest is network/framework time. Without a stage model, optimization becomes guesswork.

Reproducible AtlasMart setup

$env:NEO4J_URI='bolt://127.0.0.1:7687'$env:NEO4J_USER='neo4j'$env:NEO4J_PASSWORD='atlasmart-course-2026'$env:NEO4J_DATABASE='neo4j'py -3 -m venv .venv.\.venv\Scripts\Activate.ps1python -m pip install --upgrade pippython -m pip install neo4j==6.3.0

CYPHER 25CREATE CONSTRAINT customer_id IF NOT EXISTSFOR (c:Customer) REQUIRE c.customerId IS UNIQUE;CREATE CONSTRAINT product_id IF NOT EXISTSFOR (p:Product) REQUIRE p.productId IS UNIQUE;CREATE CONSTRAINT order_id IF NOT EXISTSFOR (o:Order) REQUIRE o.orderId IS UNIQUE;MERGE (c:Customer {customerId:'C-1001'})SET c.name='Mina Rahimi', c.tier='GOLD'MERGE (p1:Product {productId:'P-1001'})SET p1.name='Trail Camera', p1.category='Cameras', p1.price=129.90MERGE (p2:Product {productId:'P-2001'})SET p2.name='Smart Shelf Sensor', p2.category='Store IoT', p2.price=79.50MERGE (o:Order {orderId:'O-5001'})SET o.status='PAID', o.orderedAt=datetime('2026-09-08T16:30:00Z')MERGE (c)-[:PLACED]->(o)MERGE (o)-[r1:CONTAINS]->(p1)SET r1.quantity=1, r1.unitPrice=129.90MERGE (o)-[r2:CONTAINS]->(p2)SET r2.quantity=2, r2.unitPrice=79.50;

The fixture is intentionally tiny. Performance conclusions come from the synthetic workload generated by the harness, not from pretending two products are representative of production. The stable keys and uniqueness constraints make repeated batch-write experiments safe to reconcile.

1. Define the timing model before collecting numbers

Some stages overlap and driver/server summaries are not a distributed tracing system. The purpose is a useful causal decomposition, not pretending every millisecond can be perfectly attributed without clock-synchronized tracing.

2. Generate deterministic synthetic data

def make_products(n=5000):    return [        {            "productId": f"P-BENCH-{i:06d}",            "name": f"Benchmark Product {i}",            "category": "Benchmark",            "price": 10.0 + (i % 100) / 10.0,        }        for i in range(n)    ]

Keep the random/dataset seed, record count and graph density fixed between variants. If a benchmark changes the data distribution while changing concurrency, it cannot isolate causality.

3. Benchmark harness with percentiles and stage metrics

import asyncio, json, math, statistics, timefrom neo4j import AsyncGraphDatabase, QueryREAD = Query("""CYPHER 25MATCH (p:Product)WHERE p.category=$categoryRETURN p.productId AS productId, p.name AS name, p.price AS priceORDER BY p.productIdLIMIT $limit""", timeout=5.0, metadata={"app":"atlasmart-bench", "op":"product-feed"})def percentile(values, q):    xs = sorted(values)    if not xs: return None    i = min(len(xs)-1, max(0, math.ceil(q * len(xs)) - 1))    return xs[i]async def run_once(driver, gate, request_id, limit=100):    arrival = time.perf_counter()    async with gate:        admitted = time.perf_counter()        records, summary, _ = await driver.execute_query(            READ, category="Benchmark", limit=limit, database_="neo4j")        consumed = time.perf_counter()        payload = json.dumps([r.data() for r in records], separators=(",", ":")).encode()        done = time.perf_counter()    return {        "id": request_id,        "queue_ms": (admitted-arrival)*1000,        "driver_to_consumed_ms": (consumed-admitted)*1000,        "serialize_ms": (done-consumed)*1000,        "total_ms": (done-arrival)*1000,        "bytes": len(payload),        "server_available_ms": summary.result_available_after,        "server_consumed_ms": summary.result_consumed_after,    }async def benchmark(driver, requests=200, concurrency=8):    gate = asyncio.Semaphore(concurrency)    t0 = time.perf_counter()    rows = await asyncio.gather(*(run_once(driver, gate, i) for i in range(requests)))    seconds = time.perf_counter() - t0    totals = [x["total_ms"] for x in rows]    return {        "requests": requests,        "concurrency": concurrency,        "rps": requests / seconds,        "p50_ms": percentile(totals, .50),        "p95_ms": percentile(totals, .95),        "p99_ms": percentile(totals, .99),        "mean_queue_ms": statistics.fmean(x["queue_ms"] for x in rows),        "total_bytes": sum(x["bytes"] for x in rows),    }, rows

4. Sweep one variable at a time

The safe operating envelope is normally below the cliff, with margin for noisy neighbors, GC, backups/checkpoints, failover, larger tenants and temporary graph-density changes. “Maximum RPS before failure” is not a production target.

5. Observe server state without overfitting to one edition

SHOW TRANSACTIONSYIELD transactionId, currentQuery, elapsedTime, allocatedBytes, metaDataWHERE metaData.app = 'atlasmart-bench'RETURN transactionId, elapsedTime, allocatedBytes, metaData;

Available columns and privileges can vary by version/edition/security configuration. On Community, capture what is available plus host/container CPU, process memory, I/O and page-cache-relevant metrics. On Aura, use the observability exposed by the service tier rather than assuming access to self-managed files or OS counters.

6. Diagnose common benchmark lies

7. Select the operating envelope

8. Cleanup/reset

CYPHER 25MATCH (p:Product)WHERE p.productId STARTS WITH 'P-BENCH-'DETACH DELETE p;

Production judgment

Summary and next step

High-throughput Neo4j application design is a closed-loop capacity discipline: bound demand, shape results, batch deliberately, measure every stage, find saturation, and operate with headroom. Chapter 15 can now move from single-instance application throughput into cluster architecture and availability without confusing more client concurrency with high availability.

Authoritative references

• Current Neo4j versions — Current server and 5.26 LTS release snapshot.
• Neo4j Python Driver Manual — Official Python driver guide used by the mandatory async lab.
• Python Driver 6.3 API — Current synchronous and asynchronous API contracts and configuration.
• Python async API — Async driver/session/result lifecycle, cancellation and concurrency rules.
• Python concurrency guide — AsyncGraphDatabase and concurrent workflow guidance.
• Python performance recommendations — Driver performance, routing and batching guidance.
• Cypher UNWIND — List-to-row semantics and ordering boundary.
• Transaction management — Server-side transaction limits and timeout concepts.
• Python result summary — ResultSummary timing/counter API.
• Connection management — Server-side connection visibility and client user-agent evidence.
• Query planning/profile — Server operator evidence that complements driver benchmarks.