Related objects reference

class RelatedManager

A “related manager” is a manager used in a one-to-many or many-to-many related context. This happens in two cases:

• The “other side” of a ForeignKey relation. That is:

  from django.db import models
  
  class Reporter(models.Model):
      # ...
      pass
  
  class Article(models.Model):
      reporter = models.ForeignKey(Reporter)
  

  In the above example, the methods below will be available on the manager reporter.article_set.

• Both sides of a ManyToManyField relation:

  class Topping(models.Model):
      # ...
      pass
  
  class Pizza(models.Model):
      toppings = models.ManyToManyField(Topping)
  

  In this example, the methods below will be available both on topping.pizza_set and on pizza.toppings.

add(*objs)

Adds the specified model objects to the related object set.

Example:

>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b.

In the example above, in the case of a ForeignKey relationship, e.save() is called by the related manager to perform the update. Using add() with a many-to-many relationship, however, will not call any save() methods, but rather create the relationships using QuerySet.bulk_create(). If you need to execute some custom logic when a relationship is created, listen to the m2m_changed signal.

create(**kwargs)

Creates a new object, saves it and puts it in the related object set. Returns the newly created object:

>>> b = Blog.objects.get(id=1)
>>> e = b.entry_set.create(
...     headline='Hello',
...     body_text='Hi',
...     pub_date=datetime.date(2005, 1, 1)
... )

# No need to call e.save() at this point -- it's already been saved.

This is equivalent to (but much simpler than):

>>> b = Blog.objects.get(id=1)
>>> e = Entry(
...     blog=b,
...     headline='Hello',
...     body_text='Hi',
...     pub_date=datetime.date(2005, 1, 1)
... )
>>> e.save(force_insert=True)

Note that there’s no need to specify the keyword argument of the model that defines the relationship. In the above example, we don’t pass the parameter blog to create(). Django figures out that the new Entry object’s blog field should be set to b.

remove(*objs)

Removes the specified model objects from the related object set:

>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.

Similar to add(), e.save() is called in the example above to perform the update. Using remove() with a many-to-many relationship, however, will delete the relationships using QuerySet.delete() which means no model save() methods are called; listen to the m2m_changed signal if you wish to execute custom code when a relationship is deleted.

For ForeignKey objects, this method only exists if null=True. If the related field can’t be set to None (NULL), then an object can’t be removed from a relation without being added to another. In the above example, removing e from b.entry_set() is equivalent to doing e.blog = None, and because the blog ForeignKey doesn’t have null=True, this is invalid.

Changed in Django 1.7.

For ForeignKey objects, this method accepts a bulk argument to control how to perform the operation. If True (the default), QuerySet.update() is used. If bulk=False, the save() method of each individual model instance is called instead. This triggers the pre_save and post_save signals and comes at the expense of performance.

clear()

Removes all objects from the related object set:

>>> b = Blog.objects.get(id=1)
>>> b.entry_set.clear()

Note this doesn’t delete the related objects – it just disassociates them.

Just like remove(), clear() is only available on ForeignKeys where null=True and it also accepts the bulk keyword argument.

Note

Note that add(), create(), remove(), and clear() all apply database changes immediately for all types of related fields. In other words, there is no need to call save() on either end of the relationship.

Also, if you are using an intermediate model for a many-to-many relationship, some of the related manager’s methods are disabled.

Direct Assignment

A related object set can be replaced in bulk with one operation by assigning a new iterable of objects to it:

>>> new_list = [obj1, obj2, obj3]
>>> e.related_set = new_list

If the foreign key relationship has null=True, then the related manager will first call clear() to disassociate any existing objects in the related set before adding the contents of new_list. Otherwise the objects in new_list will be added to the existing related object set.