classCategory(ormar.Model):classMeta(BaseMeta):tablename="categories"id:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=40)classPost(ormar.Model):classMeta(BaseMeta):passid:int=ormar.Integer(primary_key=True)title:str=ormar.String(max_length=200)categories:Optional[List[Category]]=ormar.ManyToMany(Category)# create some sample datapost=awaitPost.objects.create(title="Hello, M2M")news=awaitCategory.objects.create(name="News")awaitpost.categories.add(news)# now you can query and access from both sides:post_check=Post.objects.select_related("categories").get()assertpost_check.categories[0]==news# query through auto registered reverse sidecategory_check=Category.objects.select_related("posts").get()assertcategory_check.posts[0]==post
Reverse relation exposes API to manage related objects also from parent side.
related_name
By default, the related_name is generated in the same way as for the ForeignKey relation (class.name.lower()+'s'),
but in the same way you can overwrite this name by providing related_name parameter like below:
When you provide multiple relations to the same model ormar can no longer auto generate
the related_name for you. Therefore, in that situation you have to provide related_name
for all but one (one can be default and generated) or all related fields.
Skipping reverse relation
If you are sure you don't want the reverse relation you can use skip_reverse=True
flag of the ManyToMany.
If you set skip_reverse flag internally the field is still registered on the other
side of the relationship so you can:
* filter by related models fields from reverse model
* order_by by related models fields from reverse model
But you cannot:
* access the related field from reverse model with related_name
* even if you select_related from reverse side of the model the returned models won't be populated in reversed instance (the join is not prevented so you still can filter and order_by over the relation)
* the relation won't be populated in dict() and json()
* you cannot pass the nested related objects when populating from dictionary or json (also through fastapi). It will be either ignored or error will be raised depending on extra setting in pydantic Config.
classCategory(ormar.Model):classMeta(BaseMeta):tablename="categories"id:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=40)classPost(ormar.Model):classMeta(BaseMeta):passid:int=ormar.Integer(primary_key=True)title:str=ormar.String(max_length=200)categories:Optional[List[Category]]=ormar.ManyToMany(Category,skip_reverse=True)# create some sample datapost=awaitPost.objects.create(title="Hello, M2M")news=awaitCategory.objects.create(name="News")awaitpost.categories.add(news)assertpost.categories[0]==news# okassertnews.posts# Attribute error!# but still can use in order_bycategories=(awaitCategory.objects.select_related("posts").order_by("posts__title").all())assertcategories[0].first_name=="Test"# note that posts are not populated for author even if explicitly# included in select_related - note no posts in dict()assertnews.dict(exclude={"id"})=={"name":"News"}# still can filter through fields of related modelcategories=awaitCategory.objects.filter(posts__title="Hello, M2M").all()assertcategories[0].name=="News"assertlen(categories)==1
Through Model
Optionally if you want to add additional fields you can explicitly create and pass
the through model class.
Note that even of you do not provide through model it's going to be created for you automatically and
still has to be included in example in alembic migrations.
Tip
Note that you need to provide through model if you want to
customize the Through model name or the database table name of this model.
If you do not provide the Through field it will be generated for you.
The default naming convention is:
for class name it's union of both classes name (parent+other) so in example above
it would be PostCategory
for table name it similar but with underscore in between and s in the end of class
lowercase name, in example above would be posts_categorys
Customizing Through relation names
By default Through model relation names default to related model name in lowercase.
So in example like this:
1 2 3 4 5 6 7 8 91011121314151617181920
...# course declaration omittedclassStudent(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)courses=ormar.ManyToMany(Course)# will produce default Through model like follows (example simplified)classStudentCourse(ormar.Model):classMeta:database=databasemetadata=metadatatablename="students_courses"id:int=ormar.Integer(primary_key=True)student=ormar.ForeignKey(Student)# default namecourse=ormar.ForeignKey(Course)# default name
To customize the names of fields/relation in Through model now you can use new parameters to ManyToMany:
through_relation_name - name of the field leading to the model in which ManyToMany is declared
through_reverse_relation_name - name of the field leading to the model to which ManyToMany leads to
Example:
1 2 3 4 5 6 7 8 910111213141516171819202122
...# course declaration ommitedclassStudent(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)courses=ormar.ManyToMany(Course,through_relation_name="student_id",through_reverse_relation_name="course_id")# will produce Through model like follows (example simplified)classStudentCourse(ormar.Model):classMeta:database=databasemetadata=metadatatablename="students_courses"id:int=ormar.Integer(primary_key=True)student_id=ormar.ForeignKey(Student)# set by through_relation_namecourse_id=ormar.ForeignKey(Course)# set by through_reverse_relation_name
Note
Note that explicitly declaring relations in Through model is forbidden, so even if you
provide your own custom Through model you cannot change the names there and you need to use
same through_relation_name and through_reverse_relation_name parameters.
Through Fields
The through field is auto added to the reverse side of the relation.
The exposed field is named as lowercase Through class name.
The exposed field explicitly has no relations loaded as the relation is already populated in ManyToMany field,
so it's useful only when additional fields are provided on Through model.
the through field can be used as a normal model field in most of the QuerySet operations.
Note that through field is attached only to related side of the query so:
1 2 3 4 5 6 7 8 910
post=awaitPost.objects.select_related("categories").get()# source model has no through fieldassertpost.postcategoryisNone# related models have through fieldassertpost.categories[0].postcategoryisnotNone# same is applicable for reversed querycategory=awaitCategory.objects.select_related("posts").get()assertcategory.postcategoryisNoneassertcategory.posts[0].postcategoryisnotNone
Note that despite that the actual instance is not populated on source model,
in queries, order by statements etc you can access through model from both sides.
So below query has exactly the same effect (note access through categories)
Note that because through fields explicitly nullifies all relation fields, as relation
is populated in ManyToMany field, you should not use the standard model methods like
save() and update() before re-loading the field from database.
If you want to modify the through field in place remember to reload it from database.
Otherwise you will set relations to None so effectively make the field useless!
1234
# always reload the field before modificationawaitpost2.categories[0].postcategory.load()# only then update the fieldawaitpost2.categories[0].postcategory.update(sort_order=3)
Note that reloading the model effectively reloads the relations as pk_only models
(only primary key is set) so they are not fully populated, but it's enough to preserve
the relation on update.
Warning
If you use i.e. fastapi the partially loaded related models on through field might cause
pydantic validation errors (that's the primary reason why they are not populated by default).
So either you need to exclude the related fields in your response, or fully load the related
models. In example above it would mean:
Preferred way of update is through queryset proxy update() method
12
# filter the desired related model with through field and update only through field paramsawaitpost2.categories.filter(name='Test category').update(postcategory={"sort_order":3})
Relation methods
add
add(item: Model, **kwargs)
Allows you to add model to ManyToMany relation.
1234
# Add a category to a post.awaitpost.categories.add(news)# or from the other end:awaitnews.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.
If you declare your models with a Through model with additional fields, you can populate them
during adding child model to relation.
In order to do so, pass keyword arguments with field names and values to add() call.
Note that this works only for ManyToMany relations.
1234
post=awaitPost(title="Test post").save()category=awaitCategory(name="Test category").save()# apart from model pass arguments referencing through model fieldsawaitpost.categories.add(category,sort_order=1,param_name='test')
remove
Removal of the related model one by one.
Removes also the relation in the database.
1
awaitnews.posts.remove(post)
clear
Removal of all related models in one call.
Removes also the relation in the database.
1
awaitnews.posts.clear()
QuerysetProxy
Reverse relation exposes QuerysetProxy API that allows you to query related model like you would issue a normal Query.
To read which methods of QuerySet are available read below querysetproxy