Learn how to build an application with Node.js that connects to the Memgraph database and executes simple queries.
Running queries directly from a web browser is not recommended because of additional requirements and possible performance issues. In other words, we encourage you to use server-side libraries and clients for top performance whenever possible.
Quickstart
With this Node.js quickstart guide learn the first steps of connecting to Memgraph and executing simple queries.
These instructions will guide you through your first steps of connecting to a running Memgraph database instance and visualizing your data using Node.js and JavaScript.
Node.js app usage and examples
Once we covered the basic concept, we can explore more advanced usages of applications built with Node.js, explain code snippets and provide more examples.
Database connection
Once the database is running, you should be able to connect to it in one of two ways:
Connect without authentication (default)
By default, the Memgraph database is running without authentication, which means that you can connect to the database without providing any credentials (username and password). If you’re running Memgraph locally, the URI should be similar to , and if you are running Memgraph on a remote server, replace with the appropriate IP address. If you ran Memgraph on a port different than 7687, do not forget to update that in the URI too.
By default, you can set username and password argument as empty strings. This means that you are connecting without authentication.
To connect a Node.js application to the Memgraph database without authentication, you can use the following code snippet:
Connect with authentication
In order to set up authentication in Memgraph, you need to create a user with a and . In Memgraph you can set a username and password by executing the following query:
Then, you can connect to the database with the following snippet:
For more details on how to create user with credentials and set authentication, visit the Memgraph authentication guide.
Query the database
After connecting your driver to Memgraph, you can start running queries. The simplest way to execute Cypher queries is by using the method. You can pass a Cypher query as a string to and it returns a result object that you can use to retrieve data from the query response.
Run a create query
The following code snippet contains a query that will create a node inside the database:
The code above creates a session that executes Cypher query that creates a new node in the database. Next, it handles any potential errors that may occur during the execution. It follows best practices by closing the session the finally block to clean up resources and maintain proper database connection management.
Run a read query
The following code snippet contains a query that will read and retrieve data from the database:
Process the results
Processing results from the database is important since we do not want to lose any data during conversions. To properly read results and serve them back to the JavaScript application, they need to be cast into proper types.
Depending on the type of request made, you can receive different results, Nodes, Relationships, Paths etc. Let’s go over a few basic examples of how to handle different types and access properties of the returned results.
First, we’re going to create a dataset in order to provide input to process our results. If you wish to follow along, below are provided queries to recreate the same dataset used.
Process the Node result
In order to process the result, you need to read them first. You can do that with the following code snippet:
The provided code snippet matches the node with the property being “Regional Manager”, runs a for loop through all the retrieved results and processes them. Assuming that the matched node has properties , and , the output should be similar to this:
Process the Relationship result
You can also receive a relationship information from a query. Let’s say we want to retrieve from the database all of the relationships with type :
The functions retrieve all of the information about certain relationships. If you’re only interested in, for example, the relationship type, ID of the start node and ID of the end node, you can replace that line of code with the following code:
It will produce the following output:
Process the Path result
You can receive paths from the database. Let’s say we want to retrieve all of the paths containing the connections of user named . Since we are only reading from the database, we’re going to use the method:
Path will contain Nodes and Relationships, that can be accessed in the same way as in the previous examples, by casting them to the relevant type.
Transactions management
When querying the database, the driver automatically creates a transaction. A transaction is a unit of work that is either committed in its entirety or rolled back on failure. For more advanced use-cases, the driver provides functions to take full control over the transaction lifecycle.
On the driver side, if a transaction fails because of a transient error, the transaction is retried automatically. The transient error will occur during write conflicts or network failures. The driver will retry the transaction function with an exponentially increasing delay.
Automatic transactions
When you execute a query using , the driver automatically creates a transaction to encapsulate the Cypher queries you’re executing. This automatic transaction management simplifies the process of working with transactions. That method should be used when transaction control is unnecessary.
Process partial results
When dealing with queries that may take considerable time to execute or have a lot of records being returned, it’s possible to handle partial results before the query reaches the set timeout. This is useful in scenarios where timeouts or other issues might interrupt the execution.
In the example below, due to the short timeout set on the query, it’s likely (and expected) that the query will be interrupted before completion. Therefore, it’s useful to handle the partial results that may be returned before the timeout occurs.
Manual transactions
Before running a transaction, you need to obtain a session. Sessions act as concrete query channels between the driver and the server, and ensure causal consistency is enforced.
Managed transactions
A transaction can contain any number of queries. As Memgraph is ACID compliant, queries within a transaction will either be executed as a whole or not at all. You cannot get a part of the transaction succeeding and another failing. Use transactions to group together related queries which work together to achieve a single logical database operation.
A managed transaction is created using the and methods, depending on whether you want to retrieve data from the database or alter it. Both methods take a transaction function callback, which is responsible for carrying out the queries and processing the results. Here’s an example of a managed transaction using the method.
Within a transaction function, a return statement results in the transaction being committed, while the transaction is automatically rolled back if an exception is raised.
Because of this, it is impossible to know how many times the transaction is going to be executed, so transaction functions should produce the same results even when run several times. This means you shouldn’t, for example, edit or rely on globals. Note that although transaction functions might be executed multiple times, the queries inside it will always run only once.
Explicit transactions
You can achieve full control over transactions by manually starting them using the method. You run queries inside an explicit transaction with the method, as you do in transaction functions.
The behavior and lifetime of an explicit transaction is controlled using the , , or methods.
Explicit transactions are useful when applications need to distribute Cypher execution across multiple functions for the same transaction or run multiple queries within a single transaction but without the automatic retries provided by managed transactions.
Process partial results
Similar to the example for the automatic transactions, partial results can be processed in the explicit transactions as well. The example below showcases handling such transactions: