Commit a96e50b7 authored by Gabriel Hurley's avatar Gabriel Hurley
Browse files

[1.2.X] Adds documentation for QuerySet.update() method. Thanks to dwillis and... 

[1.2.X] Adds documentation for QuerySet.update() method. Thanks to dwillis and timo for the majority of the wording.

Backport of [14074] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14075 bcc190cf-cafb-0310-a4f2-bffc1f526a37
parent 91310e75

docs/ref/models/querysets.txt

+25 −0
Original line number Diff line number Diff line
@@ -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