- fr
- Language: en
Please take a few minutes to complete the
2024 Django Developers Survey.
Your feedback will help guide future efforts.
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.
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
ForeignKey
s 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.
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.
_meta
API
Offline (Django 1.8):
HTML |
PDF |
ePub
Provided by Read the Docs.
© 2005-2024 Django Software Foundation and individual contributors. Django is a registered trademark of the Django Software Foundation.