UNWIND and Parameters

UNWIND and Parameters

UNWIND a list into rows. ALWAYS use $params — never string-concat into a query.

Why it matters

Driver parameters are how Neo4j gives you both safety (no injection) and speed (the planner caches the query plan keyed on shape).

Going deeper

UNWIND turns a list into rows so one statement processes a batch:

UNWIND $people AS row
MERGE (p:Person {id: row.id})
SET p.name = row.name;

with the driver passing $people as a list of maps. Two wins come together:

1. Plan caching. Neo4j caches the execution plan keyed on the query shape. Parameterized queries share one cached plan across millions of calls; string-concatenated literals produce a new shape every time and thrash the cache.
2. Injection safety. Parameters are passed out-of-band, so a value can never be parsed as Cypher — the structural defense against injection.

Pair UNWIND with CALL { ... } IN TRANSACTIONS OF N ROWS for large batches so the heap stays bounded while still using parameters throughout.

UNWIND with $parameters is a stencil and a stack of cards. The stencil (the query plan) is cut once; then you feed card after card ($param rows) through the same stencil. String-concatenating values into the query is the opposite — carving a fresh stencil for every card. Slower, and the moment a 'card' contains a quote mark, your stencil cuts the wrong shape (injection).

• String-building queries. Kills plan caching and opens injection. Fix: always pass values as $params.
• One giant UNWIND in a single transaction. Heap blowup. Fix: batch with IN TRANSACTIONS OF N ROWS.
• UNWIND of an empty list. Produces zero rows and a silent no-op. Fix: guard or assert non-empty.