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.
let { 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.
Notice that once you ask for the execution summary, the result stream is exhausted. This means that any record which has not yet been processed is discarded.
let session = driver.session({ database: 'neo4j' })
try {
let summary = await session.executeWrite(async tx => {
let 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).
let { 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
}
*/
console.log(summary.counters.containsUpdates()) // true
console.log(summary.counters.containsSystemUpdates()) // false
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 thesystem
database
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).
let result = await 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.
let result = await 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
After executing a query, the server can return notifications alongside the query result. Notifications contain recommendations for performance improvements, warnings about the usage of deprecated features, and other hints about sub-optimal usage of Neo4j.
For driver version >= 5.25 and server version >= 5.23, two forms of notifications are available (Neo4j status codes and GQL status codes).
For earlier versions, only Neo4j status codes are available. GQL status codes are planned to supersede Neo4j status codes. |
The property ResultSummary.notifications
contains a list of Notification
objects.
let { records, summary } = await driver.executeQuery(`
MATCH p=shortestPath((:Person {name: 'Alice'})-[*]->(:Person {name: 'Bob'}))
RETURN p
`, {},
{ database: 'neo4j' }
)
console.log(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'
}
]
*/
With version >= 5.25, the property ResultSummary.gqlStatusObjects
contains a list of GqlStatusObject
s.
These are GQL-compliant status objects.
Some (but not all) GqlStatusObjects
are notifications, whereas some report an outcome status: 00000
for "success", 02000
for "no data", and 00001
for "omitted result".
Summary.GqlStatusObjects()
always contains at least one entry, containing the outcome status.
let { records, summary } = await driver.executeQuery(`
MATCH p=shortestPath((:Person {name: 'Alice'})-[*]->(:Person {name: 'Bob'}))
RETURN p
`, {},
{ database: 'neo4j' }
)
console.log(summary.gqlStatusObjects)
/*
[
GqlStatusObject {
gqlStatus: '02000',
statusDescription: 'note: no data',
diagnosticRecord: { OPERATION: '', OPERATION_CODE: '0', CURRENT_SCHEMA: '/' },
position: undefined,
severity: 'UNKNOWN',
rawSeverity: undefined,
classification: 'UNKNOWN',
rawClassification: undefined,
isNotification: false
},
GqlStatusObject {
gqlStatus: '03N91',
statusDescription: "info: unbounded variable length pattern. The provided pattern `(:Person {name: 'Alice'})-[*]->(:Person {name: 'Bob'})` is unbounded. Shortest path with an unbounded pattern may result in long execution times. Use an upper limit (e.g. `[*..5]`) on the number of node hops in your pattern.",
diagnosticRecord: {
OPERATION: '',
OPERATION_CODE: '0',
CURRENT_SCHEMA: '/',
_classification: 'PERFORMANCE',
_status_parameters: [Object],
_severity: 'INFORMATION',
_position: [Object]
},
position: { offset: 24, line: 2, column: 24 },
severity: 'INFORMATION',
rawSeverity: 'INFORMATION',
classification: 'PERFORMANCE',
rawClassification: 'PERFORMANCE',
isNotification: true
}
]
*/
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 parameters minimumSeverityLevel
and/or disabledCategories
/disabledClassifications
to restrict the severity and/or category/classification of notifications that you are interested into.
There is a slight performance gain in restricting the amount of notifications the server is allowed to raise.
The severity filter applies to both Neo4j and GQL notifications.
Category and classification filters exist separately only due to the discrepancy in lexicon between GQL and Neo4j; both filters affect either form of notification though, so you should use only one of them.
You can use any of those parameters either when creating a Driver
instance, or when creating a session.
You can disable notifications altogether by setting the minimum severity to 'OFF'
.
WARNING
notifications, but not of HINT
or GENERIC
classifications// at driver level
let driver = neo4j.driver(
URI, neo4j.auth.basic(USER, PASSWORD), {
notificationsFilter: {
minimumSeverityLevel: 'WARNING', // or 'OFF' to disable entirely
disabledClassifications: ['HINT', 'GENERIC'] // filters categories as well
}
}
)
// at session level
let session = driver.session({
database: 'neo4j',
notificationsFilter: {
minimumSeverityLevel: 'WARNING', // or 'OFF' to disable entirely
disabledClassifications: ['HINT', 'GENERIC'] // filters categories as well
}
})