JavaScript client guide
Learn how to create a JavaScript application 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 JavaScript 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 JavaScript.
JavaScript client usage and examples
Once we covered the basic concept, we can explore more advanced usages of JavaScript library, 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 JavaScript client 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 takes a Cypher query as an argument and executes it to create 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 drom 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.
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 name being Memgraph, runs a for loop through all the retrieved results and processes them. Assuming that the matched node has properties , and , the output could be similar to this:
Process the Relationship result
You can also receive a relationship information from a query. For example:
With the line of code, you are able to get the all of the information about certain relationship as your output. If you’re only interested in, for example, relationship type, ID of the start node and ID of the end node, you can replace that line of code with this:
and receive an output similar to this:
Process the Path result
You can receive path from the database, using the following code snippet:
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.
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 time 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 nor 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.