This open-source repository contains all available user-defined graph analytics modules and procedures that extend the Cypher query language, written by the team behind Memgraph and its users. You can find and contribute implementations of various algorithms in multiple programming languages, all runnable inside Memgraph. This project aims to give everyone the tools they need to tackle the most challenging graph problems.
Memgraph introduces the concept of query modules,
user-defined procedures that extend the Cypher query language. These procedures are grouped into modules that can be loaded into Memgraph. How to run them can be seen on their official
documentation.
When started, Memgraph will automatically attempt to load the query modules from all *.so and *.py files it finds in the default directory defined with flag
--query-modules-directory.
If you want more info about MAGE, check out the official MAGE Documentation.
Furthermore, if you have an algorithm proposition, please fill in the survey on mage.memgraph.com.
Make sure to check out Memgraph community, and join us on a survey of streaming a graph algorithms! Drop us a message on the channels below:
- Compatibility
- Installation
- Example
- MAGE Spells
- Advanced configuration
- Developing
- Testing
- Contributing
- Code of Conduct
With changes in Memgraph API, MAGE started to track version numbers. Check out the table below which will tell you compatibility of MAGE with Memgraph versions.
| MAGE version | Memgraph version |
|---|---|
| >= 1.0 | >= 2.0.0 |
| ^0 | >= 1.4.0 <= 1.6.1 |
There are two options to install MAGE. With Docker installation you only need Docker. To build from source you will need Python3, Make, CMake, Clang, UUID and Rust. Installation with Docker is easier for quick installation and smaller development.
After installation part, you will be ready to query Memgraph and use MAGE modules. Make sure to have one of the querying platform.
Note: Here you don't need to download Github Memgraph/MAGE repository.
1. This command downloads image from Docker Hub and runs Memgraph with MAGE algorithms:
docker run -p 7687:7687 memgraph/memgraph-mage
0. Make sure that you have cloned MAGE Github repository and positioned yourself inside repo in terminal.
To clone Github repository and position yourself inside mage folder, do the following in terminal:
git clone https://github.com/memgraph/mage.git && cd mage1. To build MAGE image run the following command:
docker build -t memgraph-mage .
This will build any new algorithm added to MAGE, and load it inside Memgraph.
2. Start image with the following command and enjoy your own MAGE:
docker run --rm -p 7687:7687 --name mage memgraph-mage
NOTE: if you made any new changes while MAGE Docker container is running, you need to stop it and rebuild whole image, or you can copy mage folder inside MAGE docker container and just do the rebuild. Jump to build MAGE query modules with Docker
Note: This step is more suitable for local development.
- Linux based Memgraph package you can download here. We offer Ubuntu, Debian, Centos based Memgraph packages. To install, proceed to the following site.
- To build and install MAGE query modules you will need: Python3, Make, CMake, Clang and Rust.
Since Memgraph needs to load MAGE's modules, there is the setup script to help you.
By running following command, this script will change default directory where Memgraph is looking for query modules to your
mage/dist directory, and run build command to prepare *.so and *.py files.
python3 setup all
Note: If your changes are not loaded, make sure to restart the instance by running
systemctl stop memgraphandsystemctl start memgraph.
Next time you change something, just run the following command, since it is we have already set up new directory for query modules directory:
python3 setup build
Note that query modules are loaded into Memgraph on startup so if your instance was already running you will need to execute the following query inside one of querying platforms to load them:
If we have a graph that is broken into multiple components (left image), simple call this MAGE spell to check out which node is in which components (right image) →
// Create graph as on image below
CALL weakly_connected_components.get() YIELD node, component
RETURN node, component;
| Graph input | MAGE output |
|---|---|
 |
 |
| Algorithms | Lang | Description |
|---|---|---|
| nxalg | Python | A module that provides NetworkX integration with Memgraph and implements many NetworkX algorithms |
| graph_analyzer | Python | This Graph Analyzer query module offers insights about the stored graph or a subgraph. |
| distance_calculator | Python | Module for finding the geographical distance between two points defined with 'lng' and 'lat' coordinates. |
| tsp | Python | An algorithm for finding the shortest possible route that visits each vertex exactly once. |
| set_cover | Python | The algorithm for finding minimum cost subcollection of sets that covers all elements of a universe. |
| graph_coloring | Python | Algorithm for assigning labels to the graph elements subject to certain constraints. In this form, it is a way of coloring the graph vertices such that no two adjacent vertices are of the same color. |
| vrp | Python | Algorithm for finding the shortest route possible between the central depot and places to be visited. The algorithm can be solved with multiple vehicles that represent a visiting fleet. |
| union_find | Python | A module with an algorithm that enables the user to check whether the given nodes belong to the same connected component. |
| node_similartiy | Python | A module that contains similarity measures for calculating the similarity between two nodes. |
| node2vec_online | Python | An algorithm for calculating node embeddings as new edges arrive |
| weakly_connected_components | C++ | A module that finds weakly connected components in a graph. |
| biconnected_components | C++ | Algorithm for calculating maximal biconnected subgraph. A biconnected subgraph is a subgraph with a property that if any vertex were to be removed, the graph will remain connected. |
| bipartite_matching | C++ | Algorithm for calculating maximum bipartite matching, where matching is a set of nodes chosen in such a way that no two edges share an endpoint. |
| cycles | C++ | Algorithm for detecting cycles on graphs |
| bridges | C++ | A bridge is an edge, which when deleted, increases the number of connected components. The goal of this algorithm is to detect edges that are bridges in a graph. |
| betweenness centrality | C++ | The betweenness centrality of a node is defined as the sum of the of all-pairs shortest paths that pass through the node divided by the number of all-pairs shortest paths in the graph. The algorithm has O(nm) time complexity. |
| uuid_generator | C++ | A module that generates a new universally unique identifier (UUID). |
Run the build command of the setup script. It will generate a mage/dist directory with all the *.so and *.py files.
Flag -p (--path) represents where will contents of mage/dist directory be copied. You need to copy it to
/usr/lib/memgraph/query_modules directory, because that's where Memgraph is looking for query modules by
default.
python3 setup build -p /usr/lib/memgraph/query_modules
Note that query modules are loaded into Memgraph on startup so if your instance was already running you will need to execute the following query inside one of querying platforms to load them:
CALL mg.load_all();
setup script offers you to set your local mage/dist folder as default one for Memgraph configuration file
(flag --query-modules-directory defined in /etc/memgraph/memgraph.conf file with following step:
python3 setup modules_storage
This way Memgraph will be looking for query modules inside mage/dist folder. Now you don't need to copy mage/dist folder to
/usr/lib/memgraph/query_modules every time when you do build.
Now you can run only following command to build MAGE modules:
python3 setup build
Again the note that query modules are loaded into Memgraph on startup so if your instance was already running you will need to execute the following query inside one of querying platforms to load them:
CALL mg.load_all();
If you want to find out more about loading query modules, visit this guide.
When you developed your own query module, you need to load it inside Memgraph running inside Docker container.
There are two options here.
This command will trigger rebuild of whole Docker image. Make sure that you have added Python requirements inside python/requirements.txt
file.
1. Firstly, do the build of MAGE image:
docker build -t memgraph-mage .
2. Now, start memgraph-mage image with the following command and enjoy your own MAGE:
docker run --rm -p 7687:7687 --name mage memgraph-mage
You can build MAGE Docker image equipped for development. Rust, Clang, Python3-pip, and everything else necessary
for development will still be inside the running container. This means that you can copy MAGE repository inside the container
and do build inside mage container. And there is no need to do the whole Docker image build again.
1. To create dev MAGE image, run the following command:
docker build --target dev -t memgraph-mage:dev .
2. Now run the image with following command:
docker run --rm -p 7687:7687 --name mage memgraph-mage:dev
3. Now copying files inside container and doing build.
a) First you need to copy files to container with name mage
docker cp . mage:/mage/
b) Then you need to position yourself inside container as root:
docker exec -u root -it mage /bin/bash
Note: if you have done build locally, make sure to delete folder
cpp/buildbecause you might be dealing with differentarchitecturesor problems withCMakeCache.txt. To delete it, run:
rm -rf cpp/build
c) After that, run build and copying mage/dist to /usr/lib/memgraph/query_modules:
python3 setup build -p /usr/lib/memgraph/query_modules/
d) Everything is done now. Just run following command:
exit
Note that query modules are loaded into Memgraph on startup so if your instance was already running you will need to execute the following query inside one of querying platforms to load them:
CALL mg.load_all();
To test that everything is built, loaded, and working correctly, a python script can be run. Make sure that the Memgraph instance with MAGE is up and running.
# Running unit tests for C++ and Python
python3 test_unit
# Running end-to-end tests
python3 test_e2e
Furthermore, to test only specific end-to-end tests, you can add argument -k with substring referring to the algorithm that needs to be tested. To test a module named <query_module>, you would have to run python3 test_e2e -k <query_module> where <query_module> is the name of the specific module you want to test.
# Running specific end-to-end tests
python3 test_e2e -k weakly_connected_components
We encourage everyone to contribute with their own algorithm implementations and ideas. If you want to contribute or report a bug, please take a look at the contributions guide.
Everyone participating in this project is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to tech@memgraph.com.
Your feedback is always welcome and valuable to us. Please don't hesitate to post on our Community Forum.