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 ` + 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 ~~~~~