Build applications with Neo4j and JavaScript
The Neo4j JavaScript driver is the official library to interact with a Neo4j instance through a JavaScript application.
At the hearth of Neo4j lies Cypher, the query language to interact with a Neo4j database. While this guide does not require you to be a seasoned Cypher querier, it is going to be easier to focus on the JavaScript-specific bits if you already know some Cypher. For this reason, although this guide does also provide a gentle introduction to Cypher along the way, consider checking out Getting started → Cypher for a more detailed walkthrough of graph databases modelling and querying if this is your first approach. You may then apply that knowledge while following this guide to develop your JavaScript application.
Connect to the database
Connect to a database by creating a Driver object and providing a URL and an authentication token.
Once you have a Driver
instance, use the .getServerInfo()
method to ensure that a working connection can be established.
var neo4j = require('neo4j-driver');
(async () => {
// URI examples: 'neo4j://localhost', 'neo4j+s://xxx.databases.neo4j.io'
const URI = '<URI to Neo4j database>'
const USER = '<Username>'
const PASSWORD = '<Password>'
let driver
try {
driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD))
const serverInfo = await driver.getServerInfo()
console.log('Connection established')
console.log(serverInfo)
} catch(err) {
console.log(`Connection error\n${err}\nCause: ${err.cause}`)
}
})();
Query the database
Execute a Cypher statement with the method Driver.executeQuery()
.
Do not hardcode or concatenate parameters: use placeholders and specify the parameters as key-value pairs.
// Get the name of all 42 year-olds
const { records, summary, keys } = await driver.executeQuery(
'MATCH (p:Person {age: $age}) RETURN p.name AS name',
{ age: 42 },
{ database: 'neo4j' }
)
// Summary information
console.log(
`>> The query ${summary.query.text} ` +
`returned ${records.length} records ` +
`in ${summary.resultAvailableAfter} ms.`
)
// Loop through results and do something with them
console.log('>> Results')
for(record of records) {
console.log(record.get('name'))
}
Run your own transactions
For more advanced use-cases, you can run transactions.
Use the methods Session.executeRead()
and Session.executeWrite()
to run managed transactions.
const neo4j = require('neo4j-driver');
(async () => {
const URI = '<URI for Neo4j database>'
const USER = '<Username>'
const PASSWORD = '<Password>'
let driver, session
let employeeThreshold = 10
try {
driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD))
await driver.verifyConnectivity()
} catch(err) {
console.log(`-- Connection error --\n${err}\n-- Cause --\n${err.cause}`)
await driver.close()
return
}
session = driver.session({ database: 'neo4j' })
for(let i=0; i<100; i++) {
const name = `Neo-${i.toString()}`
const orgId = await session.executeWrite(async tx => {
let result, orgInfo
// Create new Person node with given name, if not already existing
await tx.run(`
MERGE (p:Person {name: $name})
RETURN p.name AS name
`, { name: name }
)
// Obtain most recent organization ID and number of people linked to it
result = await tx.run(`
MATCH (o:Organization)
RETURN o.id AS id, COUNT{(p:Person)-[r:WORKS_FOR]->(o)} AS employeesN
ORDER BY o.createdDate DESC
LIMIT 1
`)
if(result.records.length > 0) {
orgInfo = result.records[0]
}
if(orgInfo != undefined && orgInfo['employeesN'] == 0) {
throw new Error('Most recent organization is empty.')
// Transaction will roll back -> not even Person is created!
}
// If org does not have too many employees, add this Person to that
if(orgInfo != undefined && orgInfo['employeesN'] < employeeThreshold) {
result = await tx.run(`
MATCH (o:Organization {id: $orgId})
MATCH (p:Person {name: $name})
MERGE (p)-[r:WORKS_FOR]->(o)
RETURN $orgId AS id
`, { orgId: orgInfo['id'], name: name }
)
// Otherwise, create a new Organization and link Person to it
} else {
result = await tx.run(`
MATCH (p:Person {name: $name})
CREATE (o:Organization {id: randomuuid(), createdDate: datetime()})
MERGE (p)-[r:WORKS_FOR]->(o)
RETURN o.id AS id
`, { name: name }
)
}
// Return the Organization ID to which the new Person ends up in
return result.records[0].get('id')
})
console.log(`User ${name} added to organization ${orgId}`)
}
await session.close()
await driver.close()
})()
Close connections and sessions
Call the .close()
method on the Driver
instance when you are finished with it, to release any resources still held by it.
The same applies to any open sessions.
const driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD))
let session = driver.session({ database: 'neo4j' })
// session/driver usage
session.close()
driver.close()
API documentation
For in-depth information about driver features, check out the API documentation.
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
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.