diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/models/relations.txt | 20 | ||||
| -rw-r--r-- | docs/releases/1.9.txt | 14 |
2 files changed, 31 insertions, 3 deletions
diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index 9e27e27151..d480ec18c2 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -36,7 +36,7 @@ Related objects reference In this example, the methods below will be available both on ``topping.pizza_set`` and on ``pizza.toppings``. - .. method:: add(*objs) + .. method:: add(*objs, bulk=True) Adds the specified model objects to the related object set. @@ -48,7 +48,13 @@ Related objects reference 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. + :meth:`QuerySet.update() <django.db.models.query.QuerySet.update>` + is used to perform the update. This requires the objects to already be + saved. + + You can use the ``bulk=False`` argument to instead have the related + manager perform the update by calling ``e.save()``. + Using ``add()`` with a many-to-many relationship, however, will not call any ``save()`` methods, but rather create the relationships using :meth:`QuerySet.bulk_create() @@ -56,6 +62,12 @@ Related objects reference some custom logic when a relationship is created, listen to the :data:`~django.db.models.signals.m2m_changed` signal. + .. versionchanged:: 1.9 + + The ``bulk`` parameter was added. In order versions, foreign key + updates were always done using ``save()``. Use ``bulk=False`` if + you require the old behavior. + .. method:: create(**kwargs) Creates a new object, saves it and puts it in the related object set. @@ -135,7 +147,7 @@ Related objects reference :class:`~django.db.models.ForeignKey`\s where ``null=True`` and it also accepts the ``bulk`` keyword argument. - .. method:: set(objs, clear=False) + .. method:: set(objs, bulk=True, clear=False) .. versionadded:: 1.9 @@ -150,6 +162,8 @@ Related objects reference If ``clear=True``, the ``clear()`` method is called instead and the whole set is added at once. + The ``bulk`` argument is passed on to :meth:`add`. + Note that since ``set()`` is a compound operation, it is subject to race conditions. For instance, new objects may be added to the database in between the call to ``clear()`` and the call to ``add()``. diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt index 17d0edfa3f..b7863bab03 100644 --- a/docs/releases/1.9.txt +++ b/docs/releases/1.9.txt @@ -400,6 +400,11 @@ Models managers created by ``ForeignKey``, ``GenericForeignKey``, and ``ManyToManyField``. +* The :meth:`~django.db.models.fields.related.RelatedManager.add` method on + a reverse foreign key now has a ``bulk`` parameter to allow executing one + query regardless of the number of objects being added rather than one query + per object. + * Added the ``keep_parents`` parameter to :meth:`Model.delete() <django.db.models.Model.delete>` to allow deleting only a child's data in a model that uses multi-table inheritance. @@ -669,6 +674,15 @@ Dropped support for PostgreSQL 9.0 Upstream support for PostgreSQL 9.0 ended in September 2015. As a consequence, Django 1.9 sets 9.1 as the minimum PostgreSQL version it officially supports. +Bulk behavior of ``add()`` method of related managers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To improve performance, the ``add()`` methods of the related managers created +by ``ForeignKey`` and ``GenericForeignKey`` changed from a series of +``Model.save()`` calls to a single ``QuerySet.update()`` call. The change means +that ``pre_save`` and ``post_save`` signals aren't sent anymore. You can use +the ``bulk=False`` keyword argument to revert to the previous behavior. + Template ``LoaderOrigin`` and ``StringOrigin`` are removed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |