Memgraph supports extending the query language with user-written procedures. These procedures are grouped into modules, which can then be loaded on startup.
The Memgraph installation comes with the
modules which are located in
Assuming the standard installation on Debian, you would run Memgraph with the
When using Docker, the equivalent would be the following:
Memgraph will now attempt to load the query modules from all
files it finds in the default (
*.so modules are written using the C API and the
*.py modules are
written using the Python API. Each file corresponds to one query module. Names
of these files will be mapped to query module names. So in our case, we have
example.so which will be mapped to
example module and a
which will be mapped to
py_example module in the query language.
Each query module can define multiple procedures. Both of our examples define
a single procedure creatively named
If you want to change the directory in which Memgraph searches for query
modules, just 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).
Query procedures that allow the users to gain more insight into other query
modules and their procedures are written under our utility
mg query module.
This module offers three procedures with the following signatures:
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.
For example, invoking
mg.procedures() from openCypher like so:
might yield the following result:
In this case, we can see that Memgraph has successfully loaded all the procedures implemented in query modules including the utility query procedures.
To load a module (named e.g.
hello) that wasn't loaded on startup (perhaps
because it was added to Memgraph's query modules directory afterwards), we
can simply invoke:
If we wish to reload an existing module, say the
graph_analyzer module above, we
again use the same procedure:
Lastly, if we wish to reload all existing modules and load any newly added ones we can use:
OpenCypher has a special syntax for calling procedures in loaded query modules. For example:
Each procedure returns zero or more records, where each record contains named
YIELD part is used to select fields we are interested in. If we
are not interested in any fields, the
YIELD part can be omitted. The
procedure will still run in such a case, but the record fields will not be
stored in variables. In the above example, we assume that
will produce a record with 2 fields,
result. Trying to
fields that are not part of the produced record will result in an error.
Procedures may be called standalone as in the above example, or as a part of a larger query. This is useful if we want the procedure to work on data the query is producing. For example:
Unfortunately, when we use
CALL in a larger query, we have to explicitly
RETURN from the query to get the results. Naturally, the
RETURN is not
needed if we perform updates after
CALL. This follows the openCypher
convention that read-only queries need to end with a
RETURN, while queries
which update something don't need to
If a procedure returns a record with a field name that may clash with some variable we already have in a query, that field name can be aliased into some other name. For example:
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 be able to yield its results, you can increase the memory limit using
the following syntax:
The limit can either be specified to a specific value (either in
KB or in
MB), or it can be set to unlimited.