Skip to content

Getting started with GQLAlchemy


GQLAlchemy is an open-source Python library and an Object Graph Mapper (OGM) - a link between graph database objects and Python objects. GQLAlchemy supports Memgraph and Neo4j.

An Object Graph Mapper or OGM provides a developer-friendly workflow for writing object-oriented notation to communicate to a graph database. Instead of writing Cypher queries, you can write object-oriented code, which the OGM will automatically translate into Cypher queries.

Quick start

1. Install GQLAlchemy

Either install GQLAlchemy through pip or build it from source. If you are using Conda for Python environment management, you can install GQLAlchemy through pip.


Python 3.11 users: On Windows, GQLAlchemy is not yet compatible with this Python version. Linux users can install GQLAlchemy without the DGL extra (due to its dependencies not supporting Python 3.11 yet). If this is currently a blocker for you, please let us know by opening an issue.

2. Connect to Memgraph


To follow this guide, you will need:

  • A running Memgraph instance. If you need to set up Memgraph, take a look at the Installation guide.

Basic setup

We'll be using a Python program to demonstrate how to connect to a running Memgraph database instance.

Let's jump in and connect a simple program to Memgraph.

1. Create a new directory for your program, for example, /memgraph_python and position yourself in it.

2. Create a new Python script and name it . Add the following code to it:

from gqlalchemy import Memgraph

# Make a connection to the database
memgraph = Memgraph(host='', port=7687)

# Delete all nodes and relationships
query = "MATCH (n) DETACH DELETE n"

# Execute the query

# Create a node with the label FirstNode and message property with the value "Hello, World!"
query = """CREATE (n:FirstNode)
           SET n.message = '{message}'
           RETURN 'Node '  + id(n) + ': ' + n.message AS result""".format(message="Hello, World!")

# Execute the query
results = memgraph.execute_and_fetch(query)

# Print the first member


If the program fails to connect to a Memgraph instance that was started with Docker, you may need to use a different IP address (not the default localhost / ) to connect to the instance. You can find the CONTAINER_ID with docker ps and use it in the following command to retrieve the address:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' CONTAINER_ID

3. Now, you can run the application with the following command:

python ./

You should see an output similar to the following:

Node 1: Hello, World!

3. Learn how to use GQLAlchemy

With the help of the How-to guides you can learn how to use GQLAlchemy's features, such as object graph mapper and query builder.

3. Check the reference guide

Don't forget to check the Reference guide if you want to find out which methods GQLAlchemy has and how to use it. If the reference guide is not clear enough, head over to the GQLAlchemy repository and inspect the source code. While you're there, feel free to give us a star or contribute to this open-source Python library.