How to load MAGE query modules?
Query modules can be written using the C and C++ APIs (creating .so modules)
and the Python API (creating *.py) modules. Each file corresponds to one query
module and contains at least one procedure. 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.
When working with Docker and memgraph-platform image, you should pass
configuration flags inside of environment 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:
| Procedure | Description |
|---|---|
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.