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

1 files changed, 25 insertions, 0 deletions

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