Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fixed #24048 -- Corrected QuerySet.only() docs about interaction with defer(). #16338

Closed
wants to merge 1 commit into from
Closed

Fixed #24048 -- Corrected QuerySet.only() docs about interaction with defer(). #16338

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 11 additions & 5 deletions docs/ref/models/querysets.txt
View file
Open in desktop
Expand Up @@ -1707,9 +1707,11 @@ one, doing so will result in an error.

.. method:: only(*fields)

The ``only()`` method is more or less the opposite of :meth:`defer()`. You call
it with the fields that should *not* be deferred when retrieving a model. If
you have a model where almost all the fields need to be deferred, using
The ``only()`` method is essentially the opposite of :meth:`defer`. Only the
fields passed into this method and that are *not* already specified as deferred
are loaded immediately when the queryset is evaluated.

If you have a model where almost all the fields need to be deferred, using
``only()`` to specify the complementary set of fields can result in simpler
code.

Expand All @@ -1734,8 +1736,7 @@ logically::
# Final result is that everything except "headline" is deferred.
Entry.objects.only("headline", "body").defer("body")

# Final result loads headline and body immediately (only() replaces any
# existing set of fields).
# Final result loads headline immediately.
Entry.objects.defer("body").only("headline", "body")

All of the cautions in the note for the :meth:`defer` documentation apply to
Expand All @@ -1756,6 +1757,11 @@ are in your ``only()`` call.
deferred fields, only the loaded fields will be saved. See
:meth:`~django.db.models.Model.save()` for more details.

.. note::

When using :meth:`defer` after ``only()`` the fields in :meth:`defer` will
override ``only()`` for fields that are listed in both.

``using()``
~~~~~~~~~~~

Expand Down