diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index df0e135e790..05de43fa1f1 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -2862,15 +2862,35 @@ The ``Prefetch()`` object can be used to control the operation of The ``lookup`` argument describes the relations to follow and works the same as the string based lookups passed to -:meth:`~django.db.models.query.QuerySet.prefetch_related()`. +:meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example: + + >>> Question.objects.prefetch_related(Prefetch('choice_set')).get().choice_set.all() + [, , ] + # This will only execute two queries regardless of the number of Question + # and Choice objects. + >>> Question.objects.prefetch_related(Prefetch('choice_set')).all() + [] The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup. This is useful to further filter down the prefetch operation, or to call :meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched -relation, hence reducing the number of queries even further. +relation, hence reducing the number of queries even further: + + >>> voted_choices = Choice.objects.filter(votes__gt=0) + >>> voted_choices + [] + >>> prefetch = Prefetch('choice_set', queryset=voted_choices) + >>> Question.objects.prefetch_related(prefetch).get().choice_set.all() + [] The ``to_attr`` argument sets the result of the prefetch operation to a custom -attribute. +attribute: + + >>> prefetch = Prefetch('choice_set', queryset=voted_choices, to_attr='voted_choices') + >>> Question.objects.prefetch_related(prefetch).get().voted_choices + [] + >>> Question.objects.prefetch_related(prefetch).get().choice_set.all() + [, , ] .. note::