Skip to main content

How to run a query module


  • You have developed a query module by yourself and/or followed our tutorial for Python or C++

The following steps depend on how you installed Memgraph and MAGE as we need to import the modules.

Importing query modules into Memgraph

1. Start the MAGE container with:

docker run --rm -p 7687:7687 --name mage memgraph-mage:version-dev

Be sure to replace the version with the specific version, for example:

docker run --rm -p 7687:7687 --name mage memgraph-mage:1.4-dev

2. Copy your local MAGE directory inside the container in order for Memgraph to import the query modules:

a) First, you need to copy the files to the container named mage:

docker cp . mage:/mage/

b) Then, you need to position yourself inside the container as root:

docker exec -u root -it mage /bin/bash

Note: If you performed the build locally, make sure to delete the cpp/build directory because you might be dealing with different architectures or problems with CMakeCache.txt. To delete it, run:

rm -rf cpp/build

c) After that, build MAGE with the option to copy executables from mage/dist to /usr/lib/memgraph/query_modules:

python3 setup build -p /usr/lib/memgraph/query_modules/

d) Everything should be ready to exit the container and load the query modules:



Note that query modules are loaded into Memgraph on startup, so if your instance was already running, you would need to execute the following query inside one of the querying platforms to load them:

CALL mg.load_all();

Lastly, run a query and test your module:

MERGE (start:Node {id: 0})-[:RELATION]->(:Node {id: 1})-[:RELATION]->(:Node {id: 2})
CALL random_walk.get(start, 2) YIELD path


Test decoupled parts of your code that don't depend on Memgraph like you would in any other setting. E2e (end to end) tests, on the other hand, depend on internal Memgraph data structures, like nodes and edges. After running Memgraph, we need to prepare the testing environment on the host machine. Position yourself in the mage directory you cloned from GitHub. The expected folder structure for each module is the following:

└── e2e
└── random_walk_test
└── test_base
├── input.cyp
└── test.yml

input.cyp represents a Cypher script for entering the data into the database. To simplify this tutorial, we'll leave the database empty. test.yml specifies which test query should be run by the database and what should be the result or exception. Create the files following the aforementioned directory structure.




query: >
MATCH (start:Node {id: 0})
CALL random_walk.get(start, 2) YIELD path

output: []

Lastly, run the e2e tests with python:

python test_e2e

Next steps

Feel free to create an issue or open a pull request on our Github repo to speed up the development.
Also, don't forget to throw us a star on GitHub. ⭐