[2.2.x] Fixed #30656 -- Added QuerySet.bulk_update() to the database optimization docs.

Backport of 68aeb9016084290aac4f82860e17a9f4e941676e from master

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index 0f39fae103..9d22b980bd 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -367,6 +367,37 @@ Note that there are a number of :meth:`caveats to this method
 <django.db.models.query.QuerySet.bulk_create>`, so make sure it's appropriate
 for your use case.
 
+Update in bulk
+--------------
+
+.. versionadded:: 2.2
+
+When updating objects, where possible, use the
+:meth:`~django.db.models.query.QuerySet.bulk_update()` method to reduce the
+number of SQL queries. Given a list or queryset of objects::
+
+    entries = Entry.objects.bulk_create([
+        Entry(headline='This is a test'),
+        Entry(headline='This is only a test'),
+    ])
+
+The following example::
+
+    entries[0].headline = 'This is not a test'
+    entries[1].headline = 'This is no longer a test'
+    Entry.objects.bulk_update(entries, ['headline'])
+
+...is preferable to::
+
+    entries[0].headline = 'This is not a test'
+    entries.save()
+    entries[1].headline = 'This is no longer a test'
+    entries.save()
+
+Note that there are a number of :meth:`caveats to this method
+<django.db.models.query.QuerySet.bulk_update>`, so make sure it's appropriate
+for your use case.
+
 Insert in bulk
 --------------