Performance recommendations

Always specify the target database

Specify the target database on all queries using the database parameter, both in Driver.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 query, but becomes significant over hundreds of them.

Good practices

await driver.executeQuery('<QUERY>', {}, {database: '<DB NAME>'})
driver.session({database: '<DB NAME>'})

Bad practices

await driver.executeQuery('<QUERY>')
driver.session()

Be aware of the cost of transactions

When submitting queries through .executeQuery() or through .executeRead/Qrite(), the server automatically wraps them into a transaction. This behavior ensures that the database always ends up in a consistent state, regardless of what happens during the execution of a transaction (power outages, software crashes, etc).

Creating a safe execution context around a number of queries yields an overhead that is not present if the driver just shoots queries at the server and hopes they will get through. The overhead is small, but can add up as the number of queries increases. For this reason, if your use case values throughput more than data integrity, you may extract further performance by running all queries within a single (auto-commit) transaction. You do this by creating a session and using session.run() to run as many queries as needed.

Privilege throughput over data integrity
let session = driver.session({database: '<DB NAME>'})
for(let i=0; i<1000; i++) {
    await session.run("<QUERY>")
}
session.close()
Privilege data integrity over throughput
for(let i=0; i<1000; i++) {
    await driver.executeQuery("<QUERY>", {}, {database: '<DB NAME>'})
    // or session.executeRead/Write() calls
}

Route read queries to cluster readers

In a cluster, route read queries to any reader node. You do this by:

Good practices

await driver.executeQuery(
  'MATCH (p:Person) RETURN p.name',
  {},
  {
    routing: 'READ',  // short for neo4j.routing.READ
    database: 'neo4j'
  }
)
let session = driver.session({ database: 'neo4j' })
await session.executeRead(async tx => {
  return await tx.run('MATCH (p:Person) RETURN p.name', {})
})

Bad practices

await driver.executeQuery(
  'MATCH (p:Person) RETURN p.name',
  {},
  {
    database: 'neo4j'
  }
)
// defaults to routing = writers
let session = driver.session({ database: 'neo4j' })
await session.executeRead(async tx => {
  return await tx.run('MATCH (p:Person) RETURN p.name', {})
})
// don't ask to write on a read-only operation

Create indexes

Create indexes for properties that you often filter against. For example, if you often look up Person nodes by the name property, it is beneficial to create an index on Person.name. You can create indexes with the CREATE INDEX Cypher function, for both nodes and relationships.

// Create an index on Person.name
await driver.executeQuery('CREATE INDEX personName FOR (n:Person) ON (n.name)')

For more information, see Indexes for search performance.

Profile queries

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 the profile property of the ResultSummary object.

const 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
*/

In case some queries are so slow that you are unable to even run them in reasonable times, you can prepend them with EXPLAIN instead of PROFILE. This will return the plan that the server would use to run the query, but without executing it. The server output is available in the plan property of the ResultSummary object.

const 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: ?
*/

Specify node labels

Specify node labels in all queries. To learn how to combine labels, see Cypher → Label expressions.

Good practices

await driver.executeQuery(
  'MATCH (p:Person|Animal {name: $name}) RETURN p',
  { name: 'Alice' }
)
let session = driver.session({database: '<DB NAME>'})
await session.run(
  'MATCH (p:Person|Animal {name: $name}) RETURN p',
  { name: 'Alice' }
)

Bad practices

await driver.executeQuery(
  'MATCH (p {name: $name}) RETURN p',
  { name: 'Alice' }
)
let session = driver.session({database: '<DB NAME>'})
await session.run(
  'MATCH (p {name: $name}) RETURN p',
  { name: 'Alice' }
)

Batch data creation

Batch queries when creating a lot of records using the WITH and UNWIND Cypher clauses.

Good practice

numbers = []
for(let i=0; i<10000; i++) {
  numbers.push({value: Math.random()})
}
await 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++) {
  await 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.

Use query parameters

Use query parameters instead of hardcoding or concatenating values into queries. This allows to leverage the database’s query cache.

Good practices

await driver.executeQuery(
  'MATCH (p:Person {name: $name}) RETURN p',
  { name: 'Alice' }  // query parameters
)
let session = driver.session({database: '<DB NAME>'})
await session.run(
  'MATCH (p:Person {name: $name}) RETURN p',
  { name: 'Alice' }  // query parameters
)

Bad practices

await driver.executeQuery('MATCH (p:Person {name: "Alice"}) RETURN p')

let name = "Alice"
await driver.executeQuery('MATCH (p:Person {name: "' + name + '"}) RETURN p')
let session = driver.session({database: '<DB NAME>'})
await session.run(
  'MATCH (p:Person {name: "Alice"}) RETURN p',
  // or 'MATCH (p:Person {name: ' + name + '}) RETURN p'
  {}
)

Concurrency

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.

Use MERGE for creation only when needed

The Cypher clause MERGE is convenient for data creation, as it allows to avoid duplicate data when an exact clone of the given pattern exists. However, it requires the database to run two queries: it first needs to MATCH the pattern, and only then can it CREATE it (if needed).

If you know already that the data you are inserting is new, avoid using MERGE and use CREATE directly instead — this practically halves the number of database queries.

Filter notifications

Filter the category and/or severity of notifications the server should raise.

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.

Cypher

Cypher is Neo4j’s graph query language that lets you retrieve data from the database. 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 → 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 or executeWrite 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.