Explore the query execution summary

After all results coming from a query have been processed, the server ends the transaction by returning a summary of execution. It comes as a ResultSummary object, and it contains information among which:

  • Query counters — What changes the query triggered on the server

  • Query execution plan — How the database would execute (or executed) the query

  • Notifications — Extra information raised by the server while running the query

  • Timing information and query request summary

Retrieve the execution summary

When running queries with Driver.executeQuery(), the execution summary is part of the default return object, under the summary attribute.

const { records, summary } = await driver.executeQuery(`
  UNWIND ['Alice', 'Bob'] AS name
  MERGE (p:Person {name: name})
  `, {},
  { database: 'neo4j' }
)
// or summary = (await driver.executeQuery('<QUERY>')).summary

If you are using transaction functions, you can retrieve the query execution summary with the attribute Result.summary if you used await to resolve the result promise, or with the method Result.summary() if you consumed the result as a promise.

const session = driver.session({ database: 'neo4j' })
try {
  summary = await session.executeWrite(async tx => {
    result = await tx.run(`
        UNWIND ['Alice', 'Bob'] AS name
        MERGE (p:Person {name: name})
    `)
    return result.summary
    // or result.summary(), if you don't await tx.run()
  })
} finally {
  session.close()
}

Query counters

The property ResultSummary.counters contains counters for the operations that a query triggered (as a QueryStatistics object).

Insert some data and display the query counters
const { records, summary } = await driver.executeQuery(`
  UNWIND ['Alice', 'Bob'] AS name
  MERGE (p:Person {name: name})
  `, {},
  { database: 'neo4j' }
)
console.log(summary.counters.updates())
/*
{
  nodesCreated: 2,
  nodesDeleted: 0,
  relationshipsCreated: 0,
  relationshipsDeleted: 0,
  propertiesSet: 0,
  labelsAdded: 1,
  labelsRemoved: 0,
  indexesAdded: 0,
  indexesRemoved: 0,
  constraintsAdded: 0,
  constraintsRemoved: 0
}
*/

There are two additional methods on ResultSummary.counters which act as meta-counters:

  • .containsUpdates() — whether the query triggered any write operation on the database on which it ran

  • .containsSystemUpdates() — whether the query updated the system database

console.log(summary.counters.containsUpdates())  // true
console.log(summary.counters.containsSystemUpdates())  // false

Query execution plan

If you prefix a query with EXPLAIN, the server will return the plan it would use to run the query, but will not actually run it. The plan is then available as a Plan object under the property ResultSummary.plan, and contains the list of Cypher operators that would be used to retrieve the result set. You may use this information to locate potential bottlenecks or room for performance improvements (for example through the creation of indexes).

const result = driver.executeQuery('EXPLAIN MATCH (p {name: $name}) RETURN p', { name: 'Alice' })
console.log(result.summary.plan.arguments['string-representation'])
/*
Planner COST
Runtime PIPELINED
Runtime version 5.0
Batch size 128

+-----------------+----------------+----------------+---------------------+
| Operator        | Details        | Estimated Rows | Pipeline            |
+-----------------+----------------+----------------+---------------------+
| +ProduceResults | p              |              1 |                     |
| |               +----------------+----------------+                     |
| +Filter         | p.name = $name |              1 |                     |
| |               +----------------+----------------+                     |
| +AllNodesScan   | p              |             10 | Fused in Pipeline 0 |
+-----------------+----------------+----------------+---------------------+

Total database accesses: ?
*/

If you instead prefix a query with the keyword PROFILE, the server will return the execution plan it has used to run the query, together with profiler statistics. This includes the list of operators that were used and additional profiling information about each intermediate step. The plan is available under the property ResultSummary.profile. Notice that the query is also run, so the result object also contains any result records.

const result = driver.executeQuery('PROFILE MATCH (p {name: $name}) RETURN p', { name: 'Alice' })
console.log(result.summary.profile.arguments['string-representation'])
/*
Planner COST
Runtime PIPELINED
Runtime version 5.0
Batch size 128

+-----------------+----------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
| Operator        | Details        | Estimated Rows | Rows | DB Hits | Memory (Bytes) | Page Cache Hits/Misses | Time (ms) | Pipeline            |
+-----------------+----------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
| +ProduceResults | p              |              1 |    1 |       3 |                |                        |           |                     |
| |               +----------------+----------------+------+---------+----------------+                        |           |                     |
| +Filter         | p.name = $name |              1 |    1 |       4 |                |                        |           |                     |
| |               +----------------+----------------+------+---------+----------------+                        |           |                     |
| +AllNodesScan   | p              |             10 |    4 |       5 |            120 |                 9160/0 |   108.923 | Fused in Pipeline 0 |
+-----------------+----------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+

Total database accesses: 12, total allocated memory: 184
*/

For more information and examples, see Basic query tuning.

Notifications

The property ResultSummary.notifications contains a list of notifications coming from the server, if any were raised by the execution of the query. These include recommendations for performance improvements, warnings about the usage of deprecated features, and other hints about sub-optimal usage of Neo4j. Each notification comes as a Notification object.

An unbounded shortest path raises a performance notification
const { records, summary } = await driver.executeQuery(`
  MATCH p=shortestPath((:Person {name: 'Alice'})-[*]->(:Person {name: 'Bob'}))
  RETURN p
  `, {},
  { database: 'neo4j' }
)
print(summary.notifications)
"""
[
  Notification {
    code: 'Neo.ClientNotification.Statement.UnboundedVariableLengthPattern',
    title: 'The provided pattern is unbounded, consider adding an upper limit to the number of node hops.',
    description: 'Using shortest path with an unbounded pattern will likely result in long execution times. It is recommended to use an upper limit to the number of node hops in your pattern.',
    severity: 'INFORMATION',
    position: { offset: 24, line: 2, column: 22 },
    severityLevel: 'INFORMATION',
    rawSeverityLevel: 'INFORMATION',
    category: 'PERFORMANCE',
    rawCategory: 'PERFORMANCE'
  }
]
"""

Filter notifications

By default, the server analyses each query for all categories and severity of notifications. Starting from version 5.7, you can use the parameter notificationsFilter to restrict the severity or category of notifications that you are interested into. You may disable notifications altogether by setting the minimum severity to OFF. You can use that parameter either when creating a Driver instance, or when creating a session.

Restricting the amount of notifications the server is allowed to raise can improve performance.

Allow only WARNING notifications, but not of HINT or GENERIC category
driver = neo4j.driver(
  URI,  neo4j.auth.basic(USER, PASSWORD), {
    notificationsFilter: {
      minimumSeverityLevel: 'WARNING',  // or 'OFF' to disable entirely
      disabledCategories: ['HINT', 'GENERIC']
    }
  }
)

# at session level
session = driver.session({
    database: 'neo4j',
    notificationsFilter: {
      minimumSeverityLevel: 'WARNING',  // or 'OFF' to disable entirely
      disabledCategories: ['HINT', 'GENERIC']
    }
})