MAGE

Memgraph Advanced Graph Extensions :crystal_ball:

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.

Introduction to query modules with MAGE

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.

Further reading

If you want more info about MAGE, check out the official MAGE Documentation.

Algorithm proposition

Furthermore, if you have an algorithm proposition, please fill in the survey on mage.memgraph.com.

Community

Make sure to check out the Memgraph community and join us on a survey of streaming graph algorithms! Drop us a message on the channels below:

Overview

• Memgraph compatibility
• How to install MAGE?
  • 1. Installing MAGE with Docker
    • a) Install MAGE from Docker Hub
    • b) Install MAGE with Docker build of the repository
  • 2. Installing MAGE on Linux distro from source
• Running MAGE
• MAGE Spells
• Advanced configuration
• Testing MAGE
• Contributing
• Code of Conduct
• Feedback

Memgraph compatibility

With changes in Memgraph API, MAGE started to track version numbers. The table below lists the compatibility of MAGE with Memgraph versions.

How to install MAGE?

There are two options to install MAGE. For the Docker installation, you only need Docker installed. To build from source, you will need Python3, Make, CMake, Clang, UUID and Rust.

After the installation, you will be ready to query Memgraph and use MAGE modules. Make sure to have one of the querying platforms installed as well.

1. Installing MAGE with Docker

a) Install MAGE from Docker Hub

1. This command downloads the image from Docker Hub and runs Memgraph preloaded with MAGE modules:

docker run -p 7687:7687 memgraph/memgraph-mage

b) Install MAGE with Docker build of the repository

0. Make sure that you have cloned the MAGE Github repository and positioned yourself inside the repo in your terminal:

git clone https://github.com/memgraph/mage.git && cd mage

1. To build the 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 the container with the following command and enjoy Memgraph with MAGE:

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

NOTE: if you made any changes while the MAGE Docker container was running, you will need to stop it and rebuild the whole image, or you can copy the mage directory inside the Docker container and do the rebuild from there. To learn more about development with MAGE and Docker, visit the documentation.

2. Installing MAGE on Linux distro from source

Note: This step is more suitable for local development.

Prerequisites

• Linux based Memgraph package you can download here. We offer Ubuntu, Debian and 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, UUID and Rust.

Since Memgraph needs to load MAGE's modules, there is the setup script to help you.

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 the querying platforms to load them: CALL mg.load_all();

Running MAGE

This is an example of running the PageRank algorithm on a simple graph. You can find more details on the documentation page.

// Create the graph from the image below

CALL pagerank.get()
YIELD node, rank;

Graph input	MAGE output

MAGE Spells

Advanced configuration

• Advanced query module directories setup
• Developing MAGE with Docker

Testing MAGE

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

Contributing

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.

Code of Conduct

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 [email protected].

Feedback

Your feedback is always welcome and valuable to us. Please don't hesitate to post on our Community Forum.