EXPLAIN and PROFILE

Wiki / Cypher query language

EXPLAIN / PROFILE

Create the relevant index first. A parameter used by the query still needs a value from your driver or embedding API.

Prefix any query with EXPLAIN to see the chosen plan without executing it. The plan lists operators and, for each MATCH anchor, the scan strategy the planner picked (index seek / label scan / all-nodes scan). The anchor may be either end of the pattern — the operator line shows the scan of the end the planner chose.

EXPLAIN MATCH (p:Person {email: $e}) RETURN p;
// Match: NodeIndexSeek(:Person .email)
// ProduceResults

PROFILE <query> runs the query — including its writes — and returns, in the result summary (summary.profile in a driver), one entry per top-level clause in execution order: the operator as EXPLAIN names it, the rows it produced, the anchor candidates it examined, the nodes and relationships whose properties it loaded, and its time. Work done inside a CALL { … } or subquery expression is counted under the clause that runs it. EXPLAIN returns its plan in summary.plan as well as rows.

PROFILE MATCH (p:Person) WHERE p.age > 30 RETURN p;
// Match: NodeByLabelScan(:Person)   rows 120   candidates 5000
// ProduceResults                    rows 120   materialised 120

How the planner chooses

From version 1.2.0:

  • The smallest index seek is used. When several indexes could find a pattern's starting nodes (an equality, a range, an IN list, a list element), they are compared by how many nodes each finds, so a broad equality no longer hides a narrow range. Sizes are known for literals always, and for parameters when the query runs; EXPLAIN does not evaluate parameters, so a parameterised query may use a different index than it shows.

    EXPLAIN MATCH (p:Person) WHERE p.active = true AND p.score >= 990 RETURN p;
    // Match: NodeIndexSeekByRange(:Person .score)
    
  • Pattern order does not matter. The comma-separated patterns of one MATCH are matched selective-first when they share a variable or the WHERE relates them, so MATCH (a:Person), (b:Person {id: $id}) WHERE a.manager = b.id finds b first however it is written. Without ORDER BY the rows of such a query may arrive in a different order than in earlier versions.

  • Aggregates use constant memory per group. count, sum, avg, min and max keep a running value; collect and the DISTINCT forms keep the values they return or have seen.

How a match runs

From version 2.4.1:

  • Identity reads no properties. id(n), elementId(n), labels(n), type(r), n:Label, n IS NULL and a = b on nodes and relationships read the element's record. count(DISTINCT n), RETURN DISTINCT n and grouping by a node or relationship go by identity, and load the element once for each result row.
  • AND and OR stop when the left side decides. Put the cheaper or more selective condition first. A right side that can raise an error (arithmetic, a function call, IN) is always evaluated, so a statement that reported an error still reports it.

From version 2.4.2:

  • A filter is tested as soon as its variables are bound. In MATCH (a:Person)-[:KNOWS]->(b) WHERE a.group = 3, a person outside group 3 is dropped before any of their relationships are read. This applies to conditions joined by AND that compare properties, parameters, literals and labels, in the clause's WHERE and in inline (n WHERE …) predicates. When a filter includes arithmetic, a function call or IN, the pattern is filtered on complete matches.
  • Name the relationship type. An expansion reads each relationship's type and other end from the node's adjacency, and on the Paged engine a pattern that names one type skips the entries of every other type.
  • Shortest paths search by node. See shortestPath.

Indexes and constraints · Procedure directory · Transactions and concurrency

Planning a deployment? Review compatibility and licence setup for your instance.