What is `related_name` used for in Django?
The related_name
attribute specifies the name of the reverse relation from the User
model back to your model.
If you don't specify a related_name
, Django automatically creates one using the name of your model with the suffix _set
, for instance User.map_set.all()
.
If you do specify, e.g. related_name=maps
on the User
model, User.map_set
will still work, but the User.maps.
syntax is obviously a bit cleaner and less clunky; so for example, if you had a user object current_user
, you could use current_user.maps.all()
to get all instances of your Map
model that have a relation to current_user
.
The Django documentation has more details.
To add to existing answer - related name is a must in case there 2 FKs in the model that point to the same table. For example in case of Bill of material
@with_author
class BOM(models.Model):
name = models.CharField(max_length=200,null=True, blank=True)
description = models.TextField(null=True, blank=True)
tomaterial = models.ForeignKey(Material, related_name = 'tomaterial')
frommaterial = models.ForeignKey(Material, related_name = 'frommaterial')
creation_time = models.DateTimeField(auto_now_add=True, blank=True)
quantity = models.DecimalField(max_digits=19, decimal_places=10)
So when you will have to access this data you only can use related name
bom = material.tomaterial.all().order_by('-creation_time')
It is not working otherwise (at least I was not able to skip the usage of related name in case of 2 FK's to the same table.)
The related_name
argument is also useful if you have more complex related class names. For example, if you have a foreign key relationship:
class UserMapDataFrame(models.Model):
user = models.ForeignKey(User)
In order to access UserMapDataFrame
objects from the related User
, the default call would be User.usermapdataframe_set.all()
, which it is quite difficult to read.
Using the related_name
allows you to specify a simpler or more legible name to get the reverse relation. In this case, if you specify user = models.ForeignKey(User, related_name='map_data')
, the call would then be User.map_data.all()
.