Relations

Defining a relationship

ForeignKey

ForeignKey(to, related_name=None) has required parameters to that takes target Model class.

Sqlalchemy column and Type are automatically taken from target Model.

• Sqlalchemy column: class of a target Model primary key column
• Type (used for pydantic): type of a target Model

Defining Models

To define a relation add ForeignKey field that points to related Model.

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department)

Reverse Relation

ForeignKey fields are automatically registering reverse side of the relation.

By default it's child (source) Model name + s, like courses in snippet below:

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department)


department = Department(name='Science')
course = Course(name='Math', completed=False, department=department)

print(department.courses[0])
# Will produce:
# Course(id=None,
#        name='Math',
#        completed=False,
#        department=Department(id=None, name='Science'))

related_name

But you can overwrite this name by providing related_name parameter like below:

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department, related_name="my_courses")


department = Department(name='Science')
course = Course(name='Math', completed=False, department=department)

print(department.my_courses[0])
# Will produce:
# Course(id=None,
#        name='Math',
#        completed=False,
#        department=Department(id=None, name='Science'))

Tip

The reverse relation on access returns list of wekref.proxy to avoid circular references.

Relation Setup

You have several ways to set-up a relationship connection.

Model instance

The most obvious one is to pass a related Model instance to the constructor.

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department)


department = Department(name='Science')

# set up a relation with actual Model instance
course = Course(name='Math', completed=False, department=department)

# set up  relation with only related model pk value
course2 = Course(name='Math II', completed=False, department=department.pk)

# set up a relation with dictionary corresponding to related model
course3 = Course(name='Math III', completed=False, department=department.dict())

# explicitly set up None
course4 = Course(name='Math III', completed=False, department=None)

Primary key value

You can setup the relation also with just the pk column value of the related model.

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department)


department = Department(name='Science')

# set up a relation with actual Model instance
course = Course(name='Math', completed=False, department=department)

# set up  relation with only related model pk value
course2 = Course(name='Math II', completed=False, department=department.pk)

# set up a relation with dictionary corresponding to related model
course3 = Course(name='Math III', completed=False, department=department.dict())

# explicitly set up None
course4 = Course(name='Math III', completed=False, department=None)

Dictionary

Next option is with a dictionary of key-values of the related model.

You can build the dictionary yourself or get it from existing model with dict() method.

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department)


department = Department(name='Science')

# set up a relation with actual Model instance
course = Course(name='Math', completed=False, department=department)

# set up  relation with only related model pk value
course2 = Course(name='Math II', completed=False, department=department.pk)

# set up a relation with dictionary corresponding to related model
course3 = Course(name='Math III', completed=False, department=department.dict())

# explicitly set up None
course4 = Course(name='Math III', completed=False, department=None)

None

Finally you can explicitly set it to None (default behavior if no value passed).

import databases
import sqlalchemy

import ormar

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Department(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)


class Course(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=100)
    completed: ormar.Boolean(default=False)
    department: ormar.ForeignKey(Department)


department = Department(name='Science')

# set up a relation with actual Model instance
course = Course(name='Math', completed=False, department=department)

# set up  relation with only related model pk value
course2 = Course(name='Math II', completed=False, department=department.pk)

# set up a relation with dictionary corresponding to related model
course3 = Course(name='Math III', completed=False, department=department.dict())

# explicitly set up None
course4 = Course(name='Math III', completed=False, department=None)

Warning

In all not None cases the primary key value for related model has to exist in database.

Otherwise an IntegrityError will be raised by your database driver library.

Many2Many

Many2Many(to, through) has required parameters to and through that takes target and relation Model classes.

Sqlalchemy column and Type are automatically taken from target Model.

• Sqlalchemy column: class of a target Model primary key column
• Type (used for pydantic): type of a target Model

Defining Models:

import databases
import ormar
import sqlalchemy

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class Author(ormar.Model):
    class Meta:
        tablename = "authors"
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    first_name: ormar.String(max_length=80)
    last_name: ormar.String(max_length=80)


class Category(ormar.Model):
    class Meta:
        tablename = "categories"
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    name: ormar.String(max_length=40)


class PostCategory(ormar.Model):
    class Meta:
        tablename = "posts_categories"
        database = database
        metadata = metadata

    # If there are no additional columns id will be created automatically as Integer


class Post(ormar.Model):
    class Meta:
        tablename = "posts"
        database = database
        metadata = metadata

    id: ormar.Integer(primary_key=True)
    title: ormar.String(max_length=200)
    categories: ormar.ManyToMany(Category, through=PostCategory)
    author: ormar.ForeignKey(Author)

Create sample data:

guido = await Author.objects.create(first_name="Guido", last_name="Van Rossum")
post = await Post.objects.create(title="Hello, M2M", author=guido)
news = await Category.objects.create(name="News")

Adding related models

# Add a category to a post.
await post.categories.add(news)
# or from the other end:
await news.posts.add(post)

Warning

In all not None cases the primary key value for related model has to exist in database.

Otherwise an IntegrityError will be raised by your database driver library.

Creating new related Model instances

# Creating columns object from instance:
await post.categories.create(name="Tips")
assert len(await post.categories.all()) == 2
# newly created instance already have relation persisted in the database

Note

Note that when accessing QuerySet API methods through Many2Many relation you don't need to use objects attribute like in normal queries.

To learn more about available QuerySet methods visit queries

Removing related models

# Removal of the relationship by one
await news.posts.remove(post)
# or all at once
await news.posts.clear()

All other queryset methods

When access directly the related Many2Many field returns the list of related models.

But at the same time it exposes full QuerySet API, so you can filter, create, select related etc.

# Many to many relation exposes a list of columns models
# and an API of the Queryset:
assert news == await post.categories.get(name="News")

# with all Queryset methods - filtering, selecting columns, counting etc.
await news.posts.filter(title__contains="M2M").all()
await Category.objects.filter(posts__author=guido).get()

# columns models of many to many relation can be prefetched
news_posts = await news.posts.select_related("author").all()
assert news_posts[0].author == guido

Tip

To learn more about available QuerySet methods visit queries