This guide serves as an explanation of how to use Docker with Memgraph and setting up your development environment.
Memgraph supports custom, user-written Cypher procedures. It is easy to extend built-in features by creating your own query modules. To access those query modules, we need to take a few extra steps while using Docker and this guide will show you how to work with them.
- Lightweight - efficient in terms of system resources
- Portable - you can build locally or deploy to the cloud
- Runs on all platforms - Windows, Linux and, macOS
- Deploy in Kubernetes
To start implementing and testing custom query modules in Memgraph, it is necessary to set up a Docker container first.
The Memgraph Docker image can be downloaded here.
After successfully installing Docker, import the Memgraph Docker image with the following command:
To start Memgraph, use the following command:
At this point, Memgraph is ready for you to submit queries.
For an explanation of how to write custom query modules, follow our how-to guide.
Although unlikely, some users might experience minor difficulties after the
Docker installation. Instead of running on
localhost, a Docker container for
Memgraph may be running on a custom IP address. Fortunately, that IP address can
be found as follows:
1. Determine the ID of the Memgraph Container by issuing the command
ps. The user should get an output similar to the following:
At this point, it is important to remember the container ID of the Memgraph
Image. In our case, that is
2. Use the this ID to retrieve the IP address of the Container:
The command above will yield the IP address that should be used when connecting
to Memgraph via Memgraph Lab, mgconsole or mg_client as described in
the querying section. Just replace
HOST from the following command with the appropriate IP address:
If you wish to test and run your procedures on a custom dataset, first you need to populate the database. We will be using the CSV Import Tool which creates a snapshot that will be used by the database to recover its state on its next startup. Make sure that your Memgraph container is stopped and run the importer using the following command:
You can pass CSV files containing nodes and relationships with
--relationships flags respectively. Multiple files can be specified by
repeating either of the flags. At least one node needs to be specified, but
relationships are not required. For more information on how to structure your
CSV file, please refer to our Import tool
To import the snapshot, you will need to copy your files where Docker can see them by creating another container and filling it with your data:
To run the importer, we need to slightly modify the first command by adding the flags for nodes and relationships:
Next time you start Memgraph, your dataset will be ready for use!
Before running our custom procedures, we need to configure Memgraph to know
where to fetch query modules. By default, Memgraph will search for query modules
usr/lib/memgraph/query-modules directory. If you wish to change the
directory in which Memgraph searches for query modules, you can do it in one of
the following ways:
- change the
--query-modules-directoryflag in the main configuration file located at
- supply it as a command-line parameter
When supplying the path for our query module, first we need to mount the volume containing it. Mounting is a process by which the operating system makes files and directories on a storage device available for users to access via the computer's file system. In our case, we are allowing an isolated environment of the Docker container to access data located in our computer's file system. There are two types of mounts in Docker: volume and bind mounting. The graphic below shows the differences between the two mounting techniques:
In context of Memgraph, we will use volume mounting meaning we are going to put our files in a container and mount that container to the Docker area. Bind mounts are dependant on the file system of the host machine therefore if we move the file elsewhere, we need to re-mount. With volume binding, we have placed the files inside the Docker area and Memgraph will always have access to it no matter where they exist in our file system.
The following command should be used to successfully mount a volume containing your custom query module:
We've added two flags to the original command:
-v $(pwd)/modules:/modules- flag for mounting the volume
--query-modules-directory=/modules- flag used to change the place where Memgraph searches for modules.
Now that we have access to our query modules, we can go on and run them.
There are three ways to execute queries and procedures in Memgraph:
mg_client is a deprecated tool still coming within the Memgraph package.
mgconsole will replace
the future. If possible, please use
- using the command-line tool,
mg_client, which comes with Memgraph, (Querying)
- programmatically by using the Bolt protocol,
- from Memgraph Lab, a visual user interface that can be downloaded here.
If you've decided to use the command-line tool, you will need to run the following command:
docker run -it --entrypoint=mg_client memgraph --host HOST --use-ssl=False
HOST part of the command should be replaced with valid IP - most likely it
localhost. If you are a macOS or Linux user and are having issues with
connecting, please refer to the Note for Docker
localhost refuses to connect, try putting
After running the command, you should get a command prompt similar to this one:
Query modules are loaded on start, but you can also load them by executing the following procedure:
Each time you change a query module don't forget to reload it. The syntax for calling the procedures is as follows:
Each procedure returns either zero or more records, where each record contains
named fields. The
YIELD part is used to select fields we are interested in.
Custom procedures may be called standalone or as part of a larger query. This is
useful if we want the procedure to work on data the query is producing.
With this, your developing environment is ready and you are able to easily implement and run your own query modules. Check out our Reference Guide to see which Query Modules are included in Memgraph.