Skip to main content

How to load MAGE query modules?

Query modules can be written using C API (thus creating .so modules), and Python API (thus creating *.py) modules. Each file corresponds to one query module with one or more procedures within them. The names of these files will be mapped to the query module names. For example, a procedure node_connectivity in nxalg.py will be mapped to nxalg.node_connectivity() in the Cypher query language.

Loading query modules

Once you start Memgraph, it will attempt to load query modules from all *.so and *.py files from the default (/usr/lib/memgraph/query_modules and /var/lib/memgraph/internal_modules) directories.

MAGE modules are located at /usr/lib/memgraph/query_modules and custom modules developed via Memgraph Lab at /var/lib/memgraph/internal_modules.

Memgraph can load query modules from additional directories, if their path is added to the --query-modules-directory flag in the main configuration file (/etc/memgraph/memgraph.conf) or supplied as a command-line parameter (e.g. when using Docker).

If you are supplying the additional directory as a parameter, do not forget to include the path to /usr/lib/memgraph/query_modules, otherwise queries from that directory will not be loaded when Memgraph starts.

caution

When working with Docker and memgraph-platform image, you should pass configuration flags inside of environmental variables, for example:

docker run -p 7687:7687 -p 7444:7444 -p 3000:3000 -e MEMGRAPH="--query-modules-directory=/usr/lib/memgraph/query_modules,/usr/lib/memgraph/my_modules" memgraph/memgraph-platform`

If you are working with memgraph or memgraph-mage images you should pass configuration options like this:

docker run -p 7687:7687 -p 7444:7444 memgraph/memgraph --query-modules-directory=/usr/lib/memgraph/query_modules,/usr/lib/memgraph/my_modules

If a certain query module was added while Memgraph was already running, you need to load it manually using the mg.load("module_name") procedure within a query:

CALL mg.load("py_example");

If there is no response (no error message), the load was successful.

If you want to reload all existing modules and load any newly added ones, use mg.load_all():

CALL mg.load_all();

If there is no response (no error message), the load was successful.

You can check if the query module has been loaded by using the mg.procedures() procedure within a query:

CALL mg.procedures() YIELD *;

Utility query module

Built-in utility query module (mg) contains procedures that enable you to manage query modules files.

General procedures

Here is the list of procedures from the mg query module that can be used with all other query module files, and their signatures:

ProcedureDescription
mg.procedures() -> (name\|STRING, signature\|STRING)Lists loaded procedures and their signatures.
mg.load(module_name\|STRING) -> ()Loads or reloads the given module.
mg.load_all() -> ()Loads or reloads all modules.

mg.procedures

Lists loaded procedures and their signatures.

Example of a Cypher query:

CALL mg.procedures() YIELD *;

Example of a result:

+-------------+---------------------+-------------------+-----------------------------------------------------------------------------------------------------------------------+
| is_editable | name | path | signature |
+-------------+---------------------+-------------------+-----------------------------------------------------------------------------------------------------------------------+
| ... | ... | ... | ... |
| true | graph_analyzer.help | "/path/to/module" | graph_analyzer.help() :: (name :: STRING, value :: STRING) |
| false | mg.load | "builtin" | mg.load(module_name :: STRING) :: () |
| false | mg.load_all | "builtin" | mg.load_all() :: () |
| false | mg.procedures | "builtin" | mg.procedures() :: (name :: STRING, signature :: STRING, is_write :: BOOLEAN, path :: STRING, is_editable :: BOOLEAN) |
| ... | ... | ... | ... |
+-------------+---------------------+-------------------+-----------------------------------------------------------------------------------------------------------------------+

mg.load_all

Loads or reloads the given module.

Example of a Cypher query:

CALL mg.load_all();

If the response is Empty set (x.x sec) and there are no error messages, the update was successful.

mg.load

Loads or reloads all modules.

Example of a Cypher query:

CALL mg.load("py_example");

If the response is Empty set (x.x sec) and there are no error messages, the update was successful.