From 70e59aeaf85161ed26044c000a43af46719265ad Mon Sep 17 00:00:00 2001
From: Malcolm Tredinnick <malcolm.tredinnick@gmail.com>
Date: Fri, 26 Aug 2011 06:19:30 +0000
Subject: [PATCH] Be very clear about when it's appropriate to use defer() and
only().
I've been seeing a bit of over-reliance on defer() and only() in code
around the place and it's generally better modelled with normalised data
or shadow (unmanaged) models. This commit makes this position clearer.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16692 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
docs/ref/models/options.txt | 29 +++++++++++++++--------------
docs/ref/models/querysets.txt | 24 ++++++++++++++++++++----
2 files changed, 35 insertions(+), 18 deletions(-)
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 45304392b4..cf1b3f97e4 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -91,7 +91,8 @@ Django quotes column and table names behind the scenes.
Defaults to ``True``, meaning Django will create the appropriate database
tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
- management command. That is, Django *manages* the database tables' lifecycles.
+ management command. That is, Django *manages* the database tables'
+ lifecycles.
If ``False``, no database table creation or deletion operations will be
performed for this model. This is useful if the model represents an existing
@@ -99,21 +100,21 @@ Django quotes column and table names behind the scenes.
the *only* difference when ``managed=False``. All other aspects of
model handling are exactly the same as normal. This includes
- 1. Adding an automatic primary key field to the model if you don't declare
- it. To avoid confusion for later code readers, it's recommended to
- specify all the columns from the database table you are modeling when
- using unmanaged models.
+ 1. Adding an automatic primary key field to the model if you don't
+ declare it. To avoid confusion for later code readers, it's
+ recommended to specify all the columns from the database table you
+ are modeling when using unmanaged models.
- 2. If a model with ``managed=False`` contains a
- :class:`~django.db.models.ManyToManyField` that points to another
- unmanaged model, then the intermediate table for the many-to-many join
- will also not be created. However, the intermediary table between one
- managed and one unmanaged model *will* be created.
+ 2. If a model with ``managed=False`` contains a
+ :class:`~django.db.models.ManyToManyField` that points to another
+ unmanaged model, then the intermediate table for the many-to-many
+ join will also not be created. However, the intermediary table
+ between one managed and one unmanaged model *will* be created.
- If you need to change this default behavior, create the intermediary
- table as an explicit model (with ``managed`` set as needed) and use the
- :attr:`ManyToManyField.through` attribute to make the relation use your
- custom model.
+ If you need to change this default behavior, create the intermediary
+ table as an explicit model (with ``managed`` set as needed) and use
+ the :attr:`ManyToManyField.through` attribute to make the relation
+ use your custom model.
For tests involving models with ``managed=False``, it's up to you to ensure
the correct tables are created as part of the test setup.
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 21b2349ebc..0a8adf6446 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -139,7 +139,7 @@ Though you usually won't create one manually -- you'll go through a
clause or a default ordering on the model. ``False`` otherwise.
.. attribute:: db
-
+
The database that will be used if this query is executed now.
.. note::
@@ -906,9 +906,21 @@ eventually).
analyzed your queries closely and understand *exactly* what information
you need and have measured that the difference between returning the
fields you need and the full set of fields for the model will be
- significant. When you are initially developing your applications, don't
- bother using ``defer()``; leave it until your query construction has
- settled down and you understand where the hot-points are.
+ significant.
+
+ Even if you think you are in the advanced use-case situation, **only use
+ defer() when you cannot, at queryset load time, determine if you will need
+ the extra fields or not**. If you are frequently loading and using a
+ particular subset of your data, the best choice you can make is to
+ normalize your models and put the non-loaded data into a separate model
+ (and database table). If the columns *must* stay in the one table for some
+ reason, create a model with ``Meta.managed = False`` (see the
+ :py:attr:`managed attribute <django.db.models.Options.managed>`
+ documentation) containing just the fields you normally need to load and use
+ that where you might otherwise call ``defer()``. This makes your code more
+ explicit to the reader, is slightly faster and consumes a little less
+ memory in the Python process.
+
only
~~~~
@@ -946,6 +958,10 @@ logically::
# existing set of fields).
Entry.objects.defer("body").only("headline", "body")
+All of the cautions in the note for the :py:meth:`defer` documentation apply to
+``only()`` as well. Use it cautiously and only after exhausting your other
+options.
+
using
~~~~~