# EXPLAIN and PROFILE

[Wiki](../README.md) / [Cypher query language](README.md)

## `EXPLAIN` / `PROFILE`

Create the relevant [index](../indexes/property.md) 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.

```cypher
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.

```cypher
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.

  ```cypher
  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`](paths.md#shortestpath--allshortestpaths-unweighted-in-match).

## Related articles

[Indexes and constraints](../indexes/README.md) · [Procedure directory](../reference/procedures.md) · [Transactions and concurrency](../operations/transactions.md)
