Author: adrian Date: 2011-07-05 13:09:00 -0700 (Tue, 05 Jul 2011) New Revision: 16516
Modified: django/trunk/docs/ref/models/querysets.txt Log: Improved update() docs in querysets.txt Modified: django/trunk/docs/ref/models/querysets.txt =================================================================== --- django/trunk/docs/ref/models/querysets.txt 2011-07-05 14:16:37 UTC (rev 16515) +++ django/trunk/docs/ref/models/querysets.txt 2011-07-05 20:09:00 UTC (rev 16516) @@ -1278,25 +1278,66 @@ .. 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. +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) - # Update all the headlines belonging to this Blog. - >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same') +(This assumes your ``Entry`` model has fields ``pub_date`` and ``comments_on``.) -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()``). +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 + e.save() + +...do this:: + + Entry.objects.get(id=10).update(comments_on=False) + +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:: + + for e in Entry.objects.filter(pub_date__year=2010): + e.comments_on = False + e.save() + delete ~~~~~~ -- You received this message because you are subscribed to the Google Groups "Django updates" group. To post to this group, send email to django-updates@googlegroups.com. To unsubscribe from this group, send email to django-updates+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-updates?hl=en.
