Browse files

Improved update() docs in querysets.txt

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 89c302c commit 8b34a010171d728e3e8c26b04ed46fcb386310c4 @adrianholovaty adrianholovaty committed Jul 5, 2011
Showing with 55 additions and 14 deletions.
  1. +55 −14 docs/ref/models/querysets.txt
@@ -1278,24 +1278,65 @@ update
.. 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
+the number of rows affected.
-For example, if you wanted to update all the entries in a particular blog
-to use the same headline::
+For example, to turn comments off for all blog entries published in 2010,
+you could do this::
- >>> b = Blog.objects.get(pk=1)
+ >>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
+(This assumes your ``Entry`` model has fields ``pub_date`` and ``comments_on``.)
+You can update multiple fields -- there's no limit on how many. For example,
+here we update the ``comments_on`` and ``headline`` fields::
+ >>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')
+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, not on related models. You can't do this, for example::
+ >>> Entry.objects.update(blog__name='foo') # Won't work!
+Filtering based on related fields is still possible, though::
+ >>> Entry.objects.filter(blog__id=1).update(comments_on=True)
+You cannot call ``update()`` on a :class:`.QuerySet` that has had a slice taken
+or can otherwise no longer be filtered.
+The ``update()`` method returns the number of affected rows::
+ >>> Entry.objects.filter(id=64).update(comments_on=True)
+ 1
+ >>> Entry.objects.filter(slug='nonexistent-slug').update(comments_on=True)
+ 0
+ >>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
+ 132
+If you're just updating a record and don't need to do anything with the model
+object, you should use ``update()`` rather than loading the model object into
+memory. The former is more efficient. For example, instead of doing this::
+ e = Entry.objects.get(id=10)
+ e.comments_on = False
+ this::
+ Entry.objects.get(id=10).update(comments_on=False)
- # Update all the headlines belonging to this Blog.
- >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same')
+Finally, note that the ``update()`` method does an update at the SQL level and,
+thus, 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()``). If you want to update a bunch of records for a model that has a
+custom ``save()`` method, loop over them and call ``save()``, like this::
-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()``).
+ for e in Entry.objects.filter(pub_date__year=2010):
+ e.comments_on = False

0 comments on commit 8b34a01

Please sign in to comment.