The Neo4j JavaScript Driver
The Neo4j JavaScript Driver is available on NPM under the package name neo4j-driver.
You can install the Neo4j JavaScript Driver as a dependency by running the following command:
Importing the Library
The neo4j-driver package exports a neo4j object which contains several helper functions for interacting with Neo4j.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/src/example.ts[tag=import]
Creating a Driver Instance
The most prominent helper function on the neo4j object is the .driver() function, which accepts neo4j credentials and returns a new Driver object.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/src/example.ts[tag=driver]The function expects two arguments;
-
A Connection URI - for example,
neo4j://localhost:7687orneo4j+s://dbhash.databases.neo4j.io -
An authentication token
-
Optionally, additional driver configuration.
Authentication Types
Neo4j supports four authentication methods, basic authentication (e.g. username and password or LDAP), a base64 encoded Bearer token, a Kerberos token, or a custom authentication token. For more information on these options, visit Authentication and Authorization.
Verifying Connectivity
You can verify that the connection details used during driver instantiation are correct by calling the verifyConnectivity() method.
This function returns a Promise which throws a Neo.ClientError.Security.Unauthorized error if the provided credentials are incorrect.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/src/example.ts[tag=verify]Sessions
From the Driver object, you will open one or more sessions. A session is a client-side abstraction that borrows underlying TCP connections from a connection pool held by the Driver and uses them to communicate with Neo4j.
Sessions should be considered lightweight and disposable and can be opened and closed at will.
Once you have run all the queries you intend to run within that session, you should call the .close() method to close the session.
Calling the session.close() method releases any connections still held by the session back to the driver pool.
// Open a new session
const session = driver.session()
try {
// Run a Query
}
catch {
// Handle any errors
}
finally {
// Close the session
await session.close()
}Running a Sample Query
To run a one-off Cypher query, you can use the session.run() method.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/src/example.ts[tag=oneoff]The method accepts three arguments:
-
A string to represent a Cypher statement
-
Optionally, an object representing query parameters (prefixed in Cypher with
$) -
A third optional object containing transaction config.
For one-off queries only
If there are any transient errors when running a query, the Driver will not attempt to retry a query when usingsession.run().
For this reason, these should only be used for one-off queries and not in production.Processing Results
The res value in the sample above will implement the QueryResult interface.
The QueryResult interface guarantees access to the individual records returned by the query through the records property, which contains an array of Record instances.
The Record class has a .get() method, which provides access to the individual values held on that record.
For example, to get the (:Person) node from each record, you can write the following code:
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/src/example.ts[tag=oneoffresult]We will cover result processing in more detail in Lesson 3: Read and Write Transactions.
Closing the Driver
The Driver provides a .close() method.
Calling this function will close any open sessions, disconnect all servers, and release any resources still held by the driver.
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/src/example.ts[tag=close]Check Your Understanding
Neo4j JavaScript Driver dependency name
What name is the Neo4j JavaScript Driver registered under on NPM?
-
❏
@neo4j/driver -
❏
neo4j -
✓
neo4j-driver -
❏
neo4j-javascript-driver
Hint
The package is registered on npm as neo4j-driver.
Solution
The package is registered on npm as neo4j-driver.
Summary
In this lesson, you learned the basics of the Neo4j JavaScript Driver, how to install the dependency, create a new Driver instance, and run a sample query.
In the next lesson, you will use this knowledge to create a new Driver instance and run a Cypher statement against a Neo4j Sandbox instance.