Load and call query modules

The following page describes how query modules are loaded into Memgraph and called within a Cypher query.

If you require more information about what query modules are, please read the query modules overview page.

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) directory.

If you want to change the location from which Memgraph will load query modules, change the --query-modules-directory flag in the main configuration file (/etc/memgraph/memgraph.conf) or supply it as a command-line parameter (e.g. when using Docker).

caution

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

docker run -p 7687:7686 -e MEMGRAPH="--query-modules-directory=/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 --query-modules-directory=/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 *;

Calling query modules

Once the MAGE query modules or any custom modules you developed have been loaded into Memgraph, you can call them within queries using the following Cypher syntax:

CALL module.procedure(arg1, "string_argument", ...) YIELD res1, res2, ...;

Each procedure returns zero or more records, where each record contains named fields. The YIELD clause is used to select fields you are interested in or all of them (*). If you are not interested in any fields, omit the YIELD clause. The procedure will still run, but the record fields will not be stored in variables. If you are trying to YIELD fields that are not a part of the produced record, the query will result in an error.

Procedures can be standalone as in the example above, or a part of a larger query when we want the procedure to work on data the query is producing.

For example:

MATCH (node) CALL module.procedure(node) YIELD result RETURN *;

When the CALL clause is a part of a larger query, results from the query are returned using the RETURN clause. If the CALL clause is followed by a clause that only updates the data and doesn't read it, RETURN is unnecessary. It is the Cypher convention that read-only queries need to end with a RETURN, while queries that update something don't need to RETURN anything.

Also, if the procedure itself writes into the database, all the rest of the clauses in the query can only read from the database, and the CALL clause can only be followed by the YIELD clause and/or RETURN clause.

If a procedure returns a record with the same field name as some variable we already have in the query, that field name can be aliased with some other name using the AS sub-clause:

MATCH (result) CALL module.procedure(42) YIELD result AS procedure_result RETURN *;

Controlling procedure memory usage

When running a procedure, Memgraph controls the maximum memory usage that the procedure may consume during its execution. By default, the upper memory limit when running a procedure is 100 MB. If your query procedure requires more memory to yield its results, you can increase the memory limit using the following syntax:

CALL module.procedure(arg1, arg2, ...) PROCEDURE MEMORY LIMIT 100 KB YIELD result;
CALL module.procedure(arg1, arg2, ...) PROCEDURE MEMORY LIMIT 100 MB YIELD result;
CALL module.procedure(arg1, arg2, ...) PROCEDURE MEMORY UNLIMITED YIELD result;

The limit can either be specified to a specific value (either in KB or in MB), or it can be set to unlimited.