WITH

Generic Description

Pipeline boundary for renaming, scoping, pre-aggregation, and staged composition.

Simple example:

MATCH (p:Person) WITH p.name AS name RETURN name

Consumer-Level Explanation

Use WITH when the query must pipeline boundary for renaming, scoping, pre-aggregation, and staged composition and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

WITH is one of the most important clauses in real production Cypher. It lets you control variable scope, reduce wide intermediate rows, sort or limit before later work, import variables into subqueries, and stage a complex query into understandable phases.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after WITH must be clear
• it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
• planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Advanced Example

This example keeps WITH inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     date_trunc('day', e.ts) AS day_bucket,
     properties(d) AS doc_map,
     unpivot(properties(d.metadata)) AS metadata_rows,
     cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, day_bucket, keys(doc_map) AS doc_keys, metadata_rows, score
ORDER BY score DESC
LIMIT 15

Real Use Cases

• keeping large queries readable by turning them into phases
• reducing intermediate row width before procedure calls or subqueries
• performing aggregation or ranking before a second round of graph traversal

Real Limitations And Tradeoffs

• variables not passed through WITH disappear
• misplaced WITH boundaries can block needed columns
• too many stages can make the query verbose if they do not add semantic clarity