Custom query modules

Custom query modules

Before considering developing your custom query module, numerous graph algorithms and utility procedures have already been developed and are available as part of the MAGE library you can add to your Memgraph installation. The MAGE library is included if you use Memgraph Platform or Memgraph MAGE Docker images to run Memgraph.

You can modify them or implement custom query modules if they do not suit your needs. Memgraph supports extending the query language with user-written procedures in C, C++, Python, and Rust. These procedures are grouped into modules - query module files (either *.so or *.py files).

Developing your custom query module

To develop your custom query module procedures you can follow the guides for each language:

Each language has its own advantages and disadvantages. Python, being a dynamic language, has slower execution but offers easier writing and debugging. In contrast, modules written in C, C++, and Rust offer faster execution but are more challenging to write and debug.

Use each of the guides to ease your development process.

Every single Memgraph installation comes with the example files. For C and C++ query modules, the example files example_c.c and example_cpp.cpp are located in /usr/lib/memgraph/query_modules/src. Corresponding shared library files, example_c.so and example_cpp.so, based on these source files, are located in /usr/lib/memgraph/query_modules.

For Python query modules, there is an example.py file located in the /usr/lib/memgraph/query_modules/; there are no shared library files for Python query modules since the source is interpreted at runtime.

They were provided as examples of query modules for you to examine and learn how to use them in addition to the linked guides above.

Each query module file corresponds to one query module, and file names are mapped as query module names. For example, example.so will be mapped as example module, and py_example.py will be mapped as py_example module. If each module file has a procedure called procedure defined, those procedures would be mapped in the Cypher query language as example.procedure() and py_example.procedure() respectively.

Each query module file can contain multiple read and write procedures and functions.

Modifying the existing query modules

If existing MAGE library modules almost meet your needs, consider modifying them and make a contribution to the Memgraph Mage library.

  • Install the MAGE development environment from Docker Hub
  • Build MAGE using the docker build command
  • Build MAGE from source

Then, select a language you want to develop in.

Install MAGE and import query modules

The following steps will guide you through installing MAGE development environment from Docker Hub and importing developed query modules.

Download the MAGE image

Run the following commands to get the Memgraph and MAGE Docker image and download the toolchain used for building modules:

docker run -p 7687:7687 memgraph/memgraph-mage:<version>

Develop a query

When developing with Mage, take a look at the basis of developed algorithms and utility procedures and extend based on that.

If you are not extending the existing query modules, you can start from scratch by following these guides or using the API docs and knowledge to develop your query modules.

Start the MAGE container

Use the following command to start the MAGE container:

docker run --rm -p 7687:7687 --name mage memgraph-mage:<version>

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

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

Download and install toolchain and development dependencies

Run the make-dev-container.sh script as root within the container to download the current toolchain version and install required apt packages:

docker exec -i -u root mage bash -c "./make-dev-container.sh"

By running this command, your your container will have the following tools installed: Python3, Rust, Clang, Make, and CMake alongside the toolchain used to build both Memgraph and MAGE.

Copy the files to the container

Copy the files to the container named mage:

docker cp . mage:/mage/

Enter the container

Position yourself inside the container as memgraph:

docker exec -u memgraph -it mage /bin/bash
💡

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

Build MAGE

Activate the toolchain and build MAGE:

source /opt/toolchain-v6/activate
python3 setup build

Then copy executables from /mage/dist to /usr/lib/memgraph/query_modules as root:

docker exec -i -u root mage bash -c "cp -vr /mage/dist/* /usr/lib/memgraph/query_modules/"

Exit the container

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

exit

Querying

Query modules are loaded into Memgraph on startup, so if your instance was already running, you need to execute the following query inside one of the querying platforms (mgonsole, Memgraph Lab or a client library) to load them:

CALL mg.load_all();

Run a query and test your module. All procedures are called using the CALL clause:

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