From 6400026feb034056c0d0badcadd61804f94d8afb Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Sat, 9 Oct 2010 10:00:13 +0000 Subject: [PATCH] Fixed #14004 -- Adds documentation for QuerySet.update() method. Thanks to dwillis and timo for the majority of the wording. git-svn-id: http://code.djangoproject.com/svn/django/trunk@14074 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 09cf510b3f..8bff95308c 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1221,6 +1221,31 @@ that it will be at some point, then using ``some_query_set.exists()`` will do more overall work (an additional query) than simply using ``bool(some_query_set)``. +``update(**kwargs)`` +~~~~~~~~~~~~~~~~~~~~ + +.. method:: update(**kwargs) + +Performs an SQL update query for the specified fields, and returns +the number of rows affected. The ``update()`` method is applied instantly and +the only restriction on the :class:`QuerySet` that is updated is that it can +only update columns in the model's main table. Filtering based on related +fields is still possible. You cannot call ``update()`` on a +:class:`QuerySet` that has had a slice taken or can otherwise no longer be +filtered. + +For example, if you wanted to update all the entries in a particular blog +to use the same headline:: + + >>> b = Blog.objects.get(pk=1) + + # Update all the headlines belonging to this Blog. + >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same') + +The ``update()`` method does a bulk update and does not call any ``save()`` +methods on your models, nor does it emit the ``pre_save`` or ``post_save`` +signals (which are a consequence of calling ``save()``). + .. _field-lookups: Field lookups