EXPLAIN

Generic Description

Produce a plan without executing the query.

Simple example:

EXPLAIN MATCH (p:Person) RETURN p

Consumer-Level Explanation

Use EXPLAIN when the query must produce a plan without executing the query 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

EXPLAIN is primarily a developer and operator tool. It lets you inspect the engine's understanding of the query without paying the full execution cost or applying mutations.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after EXPLAIN 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 EXPLAIN inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

PROFILE 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, d, cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, score
ORDER BY score DESC
LIMIT 10

Real Use Cases

• plan inspection during tuning
• checking whether an optimization or rewrite took effect
• understanding how a complex query is being decomposed

Real Limitations And Tradeoffs

• it does not tell you actual runtime row counts or timings
• use PROFILE when you need execution metrics
• plan inspection still requires understanding the planner vocabulary