Neo4j Cypher traps: scope, UNION in CALL and WITH between writes

The Cypher mistakes that return wrong results or fail late: subquery scope, UNION inside CALL, vanishing rows, WITH between writes, and numeric parameters.

Published

Updated

Reading time

10 min

Picture a profile page that lists each of fifty users with their three latest posts. The query runs, returns forty-one users, and raises no error. The nine missing users have never posted, and Cypher dropped them without comment. Cypher reads like a sentence, so mistakes of this kind are easy to read straight past.

This is a collection of the traps I look for when reviewing Cypher that runs from application code, each with the smallest query that shows it and the form to write instead. If you are still deciding whether a graph belongs next to your primary store, documents and graphs comes first.

The examples use a small model: (:User {id, name})-[:FOLLOWS]->(:User) and (:User)-[:POSTED]->(:Post). They follow the current Cypher manual and the JavaScript driver manual.

A WITH clause drops everything it does not name#

The WITH page says a variable not explicitly referenced in a WITH is dropped from the scope of the rest of the query. The loud version of the mistake fails at the final RETURN, because p no longer exists:

cyphercypher
MATCH (u:User)-[:POSTED]->(p:Post)
WITH u.name AS author
RETURN author, p.title

The quiet version involves aggregation. Whatever you list in WITH and do not aggregate becomes a grouping key:

cyphercypher
MATCH (u:User)-[:POSTED]->(p:Post)
WITH u, count(p) AS posts
WHERE posts > 10
RETURN u.name, posts

Here u is the key and count(p) the aggregate. Add p.createdAt to that WITH for convenience and each group becomes a user-and-timestamp pair, every count collapses to one, and the filter returns nothing. When a count looks wrong, read the non-aggregated expressions in the preceding WITH first.

WITH also carries ORDER BY and LIMIT, which is where the next mistake lives:

cyphercypher
MATCH (u:User)-[:POSTED]->(p:Post)
WITH u, count(p) AS posts
  ORDER BY posts DESC
  LIMIT 3
SET u.topAuthor = true
RETURN u.name, posts

The LIMIT applies to the aggregated rows, so the SET touches three users. Put the LIMIT before the aggregation and it limits raw matches, so the "top" authors are whoever matched first. A LIMIT binds to the nearest preceding WITH or RETURN.

Three ways to hand a variable to a subquery#

CALL { ... } is the right tool for per-row work such as "for each user, fetch three posts". The CALL subquery page describes how an outer variable gets in:

FormSyntaxStatusCatch
Scope clauseCALL (u) { ... }CurrentSimple variable references only; no aliasing; cannot be re-declared inside
Importing WITHCALL { WITH u ... }DeprecatedMust be the first clause; cannot be followed directly by WHERE
No importCALL { ... }ValidThe subquery cannot see outer variables at all

Write the scope clause in new code. The manual notes that an importing WITH can be descoped by later clauses, while the scope clause variables are visible across the whole subquery. The importing form also forces a doubled WITH when you want to filter:

cyphercypher
MATCH (u:User)
CALL {
  WITH u
  WITH u
  WHERE u.active
  MATCH (u)-[:POSTED]->(p:Post)
  RETURN p
  ORDER BY p.createdAt DESC
  LIMIT 3
}
RETURN u.name, p.title

The second WITH u is not a typo. The scope clause removes the need for it:

cyphercypher
MATCH (u:User)
CALL (u) {
  MATCH (u)-[:POSTED]->(p:Post)
  WHERE u.active
  RETURN p
  ORDER BY p.createdAt DESC
  LIMIT 3
}
RETURN u.name, p.title

The LIMIT 3 sits inside the subquery, so it applies per outer row. That is the usual way to get "latest three per user" without collecting and slicing lists.

The subquery that deletes rows#

This is the trap behind the fifty-users example, and it costs the most because nothing looks broken. The manual states it plainly: a returning subquery that produces no rows leaves no rows after it. Users with no posts are not shown with an empty list. They are gone.

Figure 1— Rows leaving a subquery depend on whether it returns anything. Unit subqueries never change the count.

Four ways to keep the user, in the order I reach for them:

cyphercypher
// 1. Aggregate inside: an aggregation with no grouping key always yields one row
MATCH (u:User)
CALL (u) {
  MATCH (u)-[:POSTED]->(p:Post)
  RETURN count(p) AS posts
}
RETURN u.name, posts
 
// 2. OPTIONAL MATCH keeps the row and returns null
MATCH (u:User)
CALL (u) {
  OPTIONAL MATCH (u)-[:POSTED]->(p:Post)
  RETURN p
  ORDER BY p.createdAt DESC
  LIMIT 3
}
RETURN u.name, p.title
 
// 3. Collect inside, so exactly one row comes back
MATCH (u:User)
CALL (u) {
  MATCH (u)-[:POSTED]->(p:Post)
  WITH p ORDER BY p.createdAt DESC LIMIT 3
  RETURN collect(p.title) AS recent
}
RETURN u.name, recent
 
// 4. OPTIONAL CALL turns the empty result into a row of nulls
MATCH (u:User)
OPTIONAL CALL (u) {
  MATCH (u)-[:POSTED]->(p:Post)
  RETURN p
  ORDER BY p.createdAt DESC
  LIMIT 3
}
RETURN u.name, p.title

Options 1 and 3 rely on how aggregation behaves with no grouping key: it always produces a single row, with count returning 0 and collect returning an empty list. Option 4 is the manual's own answer: empty rows from an OPTIONAL CALL return null.

The mirror image is the unit subquery, one with no RETURN. It leaves the row count unchanged, which suits side effects, and it carries a reverse trap. If the subquery creates three nodes per outer row and the outer query then runs RETURN count(*), you get the number of outer rows, not of created nodes. To report what a write did, return something from the subquery or count afterwards.

UNION branches inside CALL#

UNION combines result sets from branches that each start from scratch. Three rules from the UNION page: every branch must return the same number of columns with identical names; plain UNION (or UNION DISTINCT) removes duplicates and UNION ALL keeps every row; and the order of the combined rows is unspecified, so never depend on it.

Inside a CALL there is one more. With the deprecated importing form, imported variables must be imported once per branch, and using an outer variable that only the first branch imported throws an error:

cyphercypher
MATCH (u:User)
CALL {
  WITH u
  MATCH (u)-[:FOLLOWS]->(other:User)
  RETURN other.id AS relatedId, 'follows' AS kind
  UNION
  WITH u
  MATCH (u)<-[:FOLLOWS]-(other:User)
  RETURN other.id AS relatedId, 'followedBy' AS kind
}
RETURN u.name, relatedId, kind

With the scope clause the variable is imported once and every branch sees it. The manual's own example does exactly this, a CALL (t) containing a UNION ALL whose branches both match on t:

cyphercypher
MATCH (u:User)
CALL (u) {
  MATCH (u)-[:FOLLOWS]->(other:User)
  RETURN other.id AS relatedId, 'follows' AS kind
  UNION
  MATCH (u)<-[:FOLLOWS]-(other:User)
  RETURN other.id AS relatedId, 'followedBy' AS kind
}
RETURN u.name, relatedId, kind

Two further points. Plain UNION deduplicates, and here kind keeps the branches apart; drop kind and a mutual follow collapses into one row. Use UNION ALL when rows are distinct events. And a LIMIT inside one branch limits only that branch. To cap the combined result, order and limit in an outer step after the subquery.

Write, then read: the WITH that Cypher 25 made optional#

On Cypher 5, a read clause after a write clause needs a WITH in between. The WITH page records the change: as of Cypher 25, WITH is no longer required as a separator between a write and a read.

cyphercypher
// Cypher 5: WITH separates the write from the read
CREATE (u:User {id: $id, name: $name})
WITH u
MATCH (u)-[:FOLLOWS]->(other:User)
RETURN u.id, count(other) AS following

On a database whose default is Cypher 25 the WITH u is optional, and a query copied from a Cypher 25 example into a Cypher 5 database fails. Neo4j ships both dialects, and per the version selection page Cypher 5 is frozen at the 2025.06 release while new features arrive only in Cypher 25. So pin the version rather than discover it. There are three levers: a CYPHER 25 prefix on one query; a per-database default (CREATE DATABASE ... SET DEFAULT LANGUAGE CYPHER 25, or ALTER DATABASE with the same clause); and, from Neo4j 2026.02, the db.query.default_language setting, which defaults to Cypher 5 when missing.

cyphercypher
CYPHER 25
CREATE (u:User {id: $id, name: $name})
MATCH (u)-[:FOLLOWS]->(other:User)
RETURN u.id, count(other) AS following

A query that has to behave identically everywhere keeps the explicit WITH, which is valid in both. Drop it only where a prefix or the database default guarantees Cypher 25. A local database on one default and production on another is how a query passes CI and fails in production, so set the default explicitly in both.

Batching writes: IN TRANSACTIONS and the driver call that breaks it#

For bulk updates you want inner transactions, so one failure does not roll back a million rows. The subqueries in transactions page gives the syntax:

cyphercypher
MATCH (u:User)
WHERE u.migrated IS NULL
CALL (u) {
  SET u.migrated = true
} IN TRANSACTIONS OF 1000 ROWS

ON ERROR controls failure handling: FAIL is the default, CONTINUE and BREAK ignore recoverable errors and carry on or stop, and RETRY retries transient errors with exponential delay. A CALL ... IN TRANSACTIONS inside a UNION is not supported.

The restriction that catches application code is that CALL { ... } IN TRANSACTIONS is only allowed in implicit transactions. The JavaScript driver's driver.executeQuery runs the query inside a managed transaction, which is an explicit one with automatic retries, so a batched write sent through it is rejected with GQL status 25N17, the error for this construct inside an explicit transaction. The same applies to session.executeWrite. Use a session's auto-commit run instead:

batch-migrate.tsts
import type { Driver } from "neo4j-driver";
 
export async function migrateUsers(driver: Driver) {
  const session = driver.session({ database: "neo4j" });
  try {
    // session.run is an implicit (auto-commit) transaction.
    await session.run(
      `MATCH (u:User) WHERE u.migrated IS NULL
       CALL (u) { SET u.migrated = true } IN TRANSACTIONS OF 1000 ROWS`,
    );
  } finally {
    await session.close();
  }
}

The price is that the driver does not retry implicit transactions for you, as it does for executeQuery and managed transactions. Make the migration safe to re-run (the WHERE u.migrated IS NULL guard does that) and handle retryable errors yourself.

Numbers that cross the driver as the wrong type#

The JavaScript driver sends a plain JavaScript number as a Cypher FLOAT. LIMIT and SKIP want an integer, evaluated before the query runs, so a $limit holding 20 is a float where an integer is required and the query is rejected. Two fixes: wrap the parameter in toInteger() in the query, as documents and graphs does, or send a true integer from the driver with neo4j.int:

recent-posts.tsts
import neo4j, { type Driver } from "neo4j-driver";
 
export async function recentPosts(driver: Driver, userId: string, limit: number) {
  const result = await driver.executeQuery(
    `MATCH (u:User {id: $userId})
     CALL (u) {
       MATCH (u)-[:POSTED]->(p:Post)
       RETURN p
       ORDER BY p.createdAt DESC
       LIMIT $limit
     }
     RETURN p.id AS id, p.title AS title`,
    { userId, limit: neo4j.int(limit) },
    { database: "neo4j" },
  );
  return result.records.map((r) => ({ id: r.get("id"), title: r.get("title") }));
}

The reverse direction has a setting too. By default the driver returns Cypher integers as its own Integer type, so values outside JavaScript's safe range are not silently altered. The driver config option disableLosslessIntegers: true, which the current manual still documents, makes it return plain numbers instead, at the cost of precision for large values. Decide once in the place you create the driver, not per query.

Two habits from the manual are worth copying. Never concatenate values into query text: parameterised queries are cached by structure and avoid Cypher injection. And always pass the database option, which saves a network round trip compared with resolving the user's home database.

One hypothetical shows why bounds matter: a user with 1,000 followers who each follow 1,000 accounts yields a million paths for a naive two-hop query. Put a bound inside every per-row subquery.

A review checklist#

Reviewing a Cypher query

  • Each WITH lists every variable the rest of the query needs, and nothing that changes the grouping by accident
  • Each LIMIT sits after the clause it is meant to cap
  • New subqueries use the scope clause form
  • Every returning subquery has a defined result for zero matches
  • UNION branches have identical column names, and UNION ALL is used where duplicates are real
  • The Cypher version is pinned by prefix or by database default
  • LIMIT and SKIP parameters are integers when they reach the query
  • Batched writes use IN TRANSACTIONS through session.run, not executeQuery
  • Tests include a user with no relationships, one who follows themselves, and one with a very large number of edges

The last item matters most: a fixture where every user has a post will never expose the vanishing-rows trap. And if the query needs all of these habits at once, ask whether the complexity belongs in the model. A relationship you compute with three subqueries on every read might be one you should store.

Share
All articles →