What is related_name used for?
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
If you do specify, e.g.
related_name=maps on the
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
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
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.)
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.
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