update(**kwargs)
Performs an SQL update query for the specified fields, and returns the number of rows matched (which may not be equal to the number of rows updated if some rows already have the new value).
For example, to turn comments off for all blog entries published in 2010, you could do this:
>>> 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 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 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, the most efficient approach is to call update()
, rather than loading the model object into memory. For example, instead of doing this:
e = Entry.objects.get(id=10) e.comments_on = False e.save()
...do this:
Entry.objects.filter(id=10).update(comments_on=False)
Using update()
also prevents a race condition wherein something might change in your database in the short period of time between loading the object and calling save()
.
Finally, realize that update()
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 Model.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()
Please login to continue.