diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/models/querysets.txt | 23 | ||||
| -rw-r--r-- | docs/releases/1.4.txt | 11 | ||||
| -rw-r--r-- | docs/topics/db/optimization.txt | 30 |
3 files changed, 64 insertions, 0 deletions
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index b2c521e645..898306d67d 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1158,6 +1158,29 @@ has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec. .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 +bulk_create +~~~~~~~~~~~ + +.. method:: bulk_create(objs) + +This method inserts the provided list of objects into the database in an +efficient manner (generally only 1 query, no matter how many objects there +are):: + + >>> Entry.objects.bulk_create([ + ... Entry(headline="Django 1.0 Released"), + ... Entry(headline="Django 1.1 Announced"), + ... Entry(headline="Breaking: Django is awesome") + ... ]) + +This has a number of caveats though: + + * The model's ``save()`` method will not be called, and the ``pre_save`` and + ``post_save`` signals will not be sent. + * It does not work with child models in a multi-table inheritance scenario. + * If the model's primary key is an :class:`~django.db.models.AutoField` it + does not retrieve and set the primary key attribute, as ``save()`` does. + count ~~~~~ diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 81e1b72d69..ba05f2805f 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -252,6 +252,17 @@ filename. For example, the file ``css/styles.css`` would also be saved as See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` docs for more information. +``Model.objects.bulk_create`` in the ORM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This method allows for more efficient creation of multiple objects in the ORM. +It can provide significant performance increases if you have many objects, +Django makes use of this internally, meaning some operations (such as database +setup for test suites) has seen a performance benefit as a result. + +See the :meth:`~django.db.models.query.QuerySet.bulk_create` docs for more +information. + Minor features ~~~~~~~~~~~~~~ diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 265ef55fae..5093917b61 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -268,3 +268,33 @@ instead of:: entry.blog.id +Insert in bulk +============== + +When creating objects, where possible, use the +:meth:`~django.db.models.query.QuerySet.bulk_create()` method to reduce the +number of SQL queries. For example:: + + Entry.objects.bulk_create([ + Entry(headline="Python 3.0 Released"), + Entry(headline="Python 3.1 Planned") + ]) + +Is preferable to:: + + Entry.objects.create(headline="Python 3.0 Released") + Entry.objects.create(headline="Python 3.1 Planned") + +Note that there are a number of :meth:`caveats to this method +<django.db.models.query.QuerySet.bulk_create>`, make sure it is appropriate for +your use case. This also applies to :class:`ManyToManyFields +<django.db.models.ManyToManyField>`, doing:: + + my_band.members.add(me, my_friend) + +Is preferable to:: + + my_band.members.add(me) + my_band.members.add(my_friend) + +Where ``Bands`` and ``Artists`` have a many-to-many relationship. |