Performance recommendations
-
Specify the target database on all queries using the
database
parameter, both inDriver.executeQuery()
calls and when creating new sessions. If no database is provided, the driver has to send an extra request to the server to figure out what the default database is. The overhead is minimal for a single session, but becomes significant over hundreds of sessions.// Good practice driver.executeQuery('<QUERY>', {}, {database: '<DB NAME>'}) driver.session({database: '<DB NAME>'})
// Bad practice driver.executeQuery('<QUERY>') driver.session()
-
Use query parameters instead of hardcoding or concatenating values into queries. This allows to leverage the database’s query cache.
// Good practice driver.executeQuery( 'MATCH (p:Person {name: $name}) RETURN p', { name: 'Alice' } // query parameters )
// Bad practice driver.executeQuery('MATCH (p:Person {name: "Alice"}) RETURN p') driver.executeQuery('MATCH (p:Person {name: ' + name + '}) RETURN p')
-
Specify node labels in all queries. To learn how to combine labels, see Cypher — Label expressions.
// Good practice driver.executeQuery('MATCH (p:Person|Animal {name: $name}) RETURN p', { name: 'Alice' })
// Bad practice driver.executeQuery('MATCH (p {name: $name}) RETURN p', { name: 'Alice' })
-
Batch queries when creating a lot of records using the
WITH
andUNWIND
Cypher clauses.// Good practice numbers = [] for(let i=0; i<10000; i++) { numbers.push({value: Math.random()}) } driver.executeQuery(` WITH $numbers AS batch UNWIND batch AS node MERGE (n:Number {value: node.value}) `, { numbers: numbers } )
// Bad practice for(let i=0; i<10000; i++) { driver.executeQuery('MERGE (:Number {value: $value})', { value: Math.random() }) }
The most efficient way of performing a first import of large amounts of data into a new database is the neo4j-admin database import
command. -
Create indexes for properties that you often filter against. For example, if you often look up
Person
nodes by thename
property, it is beneficial to create an index onPerson.name
. You can create indexes with theCREATE INDEX
Cypher function, for both nodes and relationships. For more information, see Indexes for search performance.// Create an index on Person.name driver.executeQuery('CREATE INDEX personName FOR (n:Person) ON (n.name)')
-
Profile your queries to locate queries whose performance can be improved. You can profile queries by prepending them with
PROFILE
. The server output is available in theprofile
property of theResultSummary
object.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 */
If your query is so slow that you are unable to even run it in a reasonable time, you can prepend it with
EXPLAIN
instead ofPROFILE
. This will return the plan that the server would use to run the query, but without executing it. The server output is available in theplan
property of theResultSummary
object.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: ? */
-
Use asynchronous querying. This is likely to be more impactful on performance if you parallelize complex and time-consuming queries in your application, but not so much if you run many simple ones.
Glossary
- LTS
-
A Long Term Support release is one guaranteed to be supported for a number of years. Neo4j 4.4 is LTS, and Neo4j 5 will also have an LTS version.
- Aura
-
Aura is Neo4j’s fully managed cloud service. It comes with both free and paid plans. Every Neo4j-backed application requires a
Driver
object. - Cypher
-
Cypher is Neo4j’s graph query language that lets you retrieve data from the graph. It is like SQL, but for graphs.
- APOC
-
Awesome Procedures On Cypher (APOC) is a library of (many) functions that can not be easily expressed in Cypher itself.
- Bolt
-
Bolt is the protocol used for interaction between Neo4j instances and drivers. It listens on port 7687 by default.
- ACID
-
Atomicity, Consistency, Isolation, Durability (ACID) are properties guaranteeing that database transactions are processed reliably. An ACID-compliant DBMS ensures that the data in the database remains accurate and consistent despite failures.
- eventual consistency
-
A database is eventually consistent if it provides the guarantee that all cluster members will, at some point in time, store the latest version of the data.
- causal consistency
-
A database is causally consistent if read and write queries are seen by every member of the cluster in the same order. This is stronger than eventual consistency.
- null
-
The null marker is not a type but a placeholder for absence of value. For more information, see Cypher Manual — Working with
null
. - transaction
-
A transaction is a unit of work that is either committed in its entirety or rolled back on failure. An example is a bank transfer: it involves multiple steps, but they must all succeed or be reverted, to avoid money being subtracted from one account but not added to the other.
- backpressure
-
Backpressure is a force opposing the flow of data. It ensures that the client is not being overwhelmed by data faster than it can handle.
- transaction function
-
A transaction function is a callback executed by an
executeRead
orexecuteWrite
call. The driver automatically re-executes the callback in case of server failure. - Driver
-
A
Driver
object holds the details required to establish connections with a Neo4j database.
Was this page helpful?