documented RelatedManager calling save() behind the scenes, added section on direct replacement of related object set
This commit is contained in:
parent
a91799a30c
commit
a5bcc09c8f
docs/ref/models
|
@ -36,7 +36,10 @@ Related objects reference
|
||||||
In this example, the methods below will be available both on
|
In this example, the methods below will be available both on
|
||||||
``topping.pizza_set`` and on ``pizza.toppings``.
|
``topping.pizza_set`` and on ``pizza.toppings``.
|
||||||
|
|
||||||
These related managers have some extra methods:
|
.. _related-manager-methods:
|
||||||
|
|
||||||
|
Related Manager Methods
|
||||||
|
-----------------------
|
||||||
|
|
||||||
.. method:: add(obj1, [obj2, ...])
|
.. method:: add(obj1, [obj2, ...])
|
||||||
|
|
||||||
|
@ -48,7 +51,9 @@ Related objects reference
|
||||||
>>> e = Entry.objects.get(id=234)
|
>>> e = Entry.objects.get(id=234)
|
||||||
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
|
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
|
||||||
|
|
||||||
In the example above, ``e.save()`` is called to perform the update.
|
In the example above, in the case of a
|
||||||
|
:class:`~django.db.models.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
|
Using ``add()`` with a many-to-many relationship, however, will not
|
||||||
call any ``save()`` methods, but rather create the relationships
|
call any ``save()`` methods, but rather create the relationships
|
||||||
using :meth:`QuerySet.bulk_create()
|
using :meth:`QuerySet.bulk_create()
|
||||||
|
@ -122,3 +127,26 @@ Related objects reference
|
||||||
|
|
||||||
Just like ``remove()``, ``clear()`` is only available on
|
Just like ``remove()``, ``clear()`` is only available on
|
||||||
:class:`~django.db.models.ForeignKey`\s where ``null=True``.
|
:class:`~django.db.models.ForeignKey`\s where ``null=True``.
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
.. _direct-assignment:
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
Loading…
Reference in New Issue