fromtypingimportOptionalimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classDepartment(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)department:Optional[Department]=ormar.ForeignKey(Department)department=awaitDepartment(name="Science").save()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'))
Reverse relation exposes API to manage related objects also from parent side.
Skipping reverse relation
If you are sure you don't want the reverse relation you can use skip_reverse=True
flag of the ForeignKey.
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.
classAuthor(ormar.Model):classMeta(BaseMeta):passid:int=ormar.Integer(primary_key=True)first_name:str=ormar.String(max_length=80)last_name:str=ormar.String(max_length=80)classPost(ormar.Model):classMeta(BaseMeta):passid:int=ormar.Integer(primary_key=True)title:str=ormar.String(max_length=200)author:Optional[Author]=ormar.ForeignKey(Author,skip_reverse=True)# create sample dataauthor=Author(first_name="Test",last_name="Author")post=Post(title="Test Post",author=author)assertpost.author==author# okassertauthor.posts# Attribute error!# but still can use in order_byauthors=(awaitAuthor.objects.select_related("posts").order_by("posts__title").all())assertauthors[0].first_name=="Test"# note that posts are not populated for author even if explicitly# included in select_related - note no posts in dict()assertauthor.dict(exclude={"id"})=={"first_name":"Test","last_name":"Author"}# still can filter through fields of related modelauthors=awaitAuthor.objects.filter(posts__title="Test Post").all()assertauthors[0].first_name=="Test"assertlen(authors)==1
add
Adding child model from parent side causes adding related model to currently loaded parent relation,
as well as sets child's model foreign key value and updates the model.
123456789
department=awaitDepartment(name="Science").save()course=Course(name="Math",completed=False)# note - not savedawaitdepartment.courses.add(course)assertcourse.pkisnotNone# child model was saved# relation on child model is set and FK column saved in dbassertcourse.department==department# relation on parent model is also setassertdepartment.courses[0]==course
Warning
If you want to add child model on related model the primary key value for parent model has to exist in database.
Otherwise ormar will raise RelationshipInstanceError as it cannot set child's ForeignKey column value
if parent model has no primary key value.
That means that in example above the department has to be saved before you can call department.courses.add().
Warning
This method will not work on ManyToMany relations - there, both sides of the relation have to be saved before adding to relation.
remove
Removal of the related model one by one.
In reverse relation calling remove() does not remove the child model, but instead nulls it ForeignKey value.
123456789
# continuing from aboveawaitdepartment.courses.remove(course)assertlen(department.courses)==0# course still exists and was saved in removeassertcourse.pkisnotNoneassertcourse.departmentisNone# to remove child from dbawaitcourse.delete()
But if you want to clear the relation and delete the child at the same time you can issue:
123
# this will not only clear the relation # but also delete related course from dbawaitdepartment.courses.remove(course,keep_reversed=False)
clear
Removal of all related models in one call.
Like remove by default clear() nulls the ForeigKey column on child model (all, not matter if they are loaded or not).
12
# nulls department column on all courses related to this departmentawaitdepartment.courses.clear()
If you want to remove the children altogether from the database, set keep_reversed=False
12
# deletes from db all courses related to this department awaitdepartment.courses.clear(keep_reversed=False)
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
related_name
But you can overwrite this name by providing related_name parameter like below:
fromtypingimportOptionalimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classDepartment(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)department:Optional[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.
Warning
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.
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.
fromtypingimportOptional,Dict,Unionimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classDepartment(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)department:Optional[Union[Department,Dict]]=ormar.ForeignKey(Department)department=Department(name="Science")# set up a relation with actual Model instancecourse=Course(name="Math",completed=False,department=department)# set up relation with only related model pk valuecourse2=Course(name="Math II",completed=False,department=department.pk)# set up a relation with dictionary corresponding to related modelcourse3=Course(name="Math III",completed=False,department=department.dict())# explicitly set up Nonecourse4=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.
fromtypingimportOptional,Dict,Unionimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classDepartment(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)department:Optional[Union[Department,Dict]]=ormar.ForeignKey(Department)department=Department(name="Science")# set up a relation with actual Model instancecourse=Course(name="Math",completed=False,department=department)# set up relation with only related model pk valuecourse2=Course(name="Math II",completed=False,department=department.pk)# set up a relation with dictionary corresponding to related modelcourse3=Course(name="Math III",completed=False,department=department.dict())# explicitly set up Nonecourse4=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.
fromtypingimportOptional,Dict,Unionimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classDepartment(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)department:Optional[Union[Department,Dict]]=ormar.ForeignKey(Department)department=Department(name="Science")# set up a relation with actual Model instancecourse=Course(name="Math",completed=False,department=department)# set up relation with only related model pk valuecourse2=Course(name="Math II",completed=False,department=department.pk)# set up a relation with dictionary corresponding to related modelcourse3=Course(name="Math III",completed=False,department=department.dict())# explicitly set up Nonecourse4=Course(name="Math III",completed=False,department=None)
None
Finally you can explicitly set it to None (default behavior if no value passed).
fromtypingimportOptional,Dict,Unionimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classDepartment(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)department:Optional[Union[Department,Dict]]=ormar.ForeignKey(Department)department=Department(name="Science")# set up a relation with actual Model instancecourse=Course(name="Math",completed=False,department=department)# set up relation with only related model pk valuecourse2=Course(name="Math II",completed=False,department=department.pk)# set up a relation with dictionary corresponding to related modelcourse3=Course(name="Math III",completed=False,department=department.dict())# explicitly set up Nonecourse4=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.