Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #20513 - Expanded docs on QuerySet caching.

Thanks seddonym.
  • Loading branch information...
commit 8365d76da01af1d4391cba32d62178791d074b06 1 parent 33dd8f5
Tim Graham authored May 28, 2013

Showing 1 changed file with 40 additions and 3 deletions. Show diff stats Hide diff stats

  1. 43  docs/topics/db/queries.txt
43  docs/topics/db/queries.txt
@@ -714,9 +714,9 @@ for you transparently.
714 714
 Caching and QuerySets
715 715
 ---------------------
716 716
 
717  
-Each :class:`~django.db.models.query.QuerySet` contains a cache, to minimize
718  
-database access. It's important to understand how it works, in order to write
719  
-the most efficient code.
  717
+Each :class:`~django.db.models.query.QuerySet` contains a cache to minimize
  718
+database access. Understanding how it works will allow you to write the most
  719
+efficient code.
720 720
 
721 721
 In a newly created :class:`~django.db.models.query.QuerySet`, the cache is
722 722
 empty. The first time a :class:`~django.db.models.query.QuerySet` is evaluated
@@ -747,6 +747,43 @@ To avoid this problem, simply save the
747 747
     >>> print([p.headline for p in queryset]) # Evaluate the query set.
748 748
     >>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.
749 749
 
  750
+When querysets are not cached
  751
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  752
+
  753
+Querysets do not always cache their results.  When evaluating only *part* of
  754
+the queryset, the cache is checked, but if it is not populated then the items
  755
+returned by the subsequent query are not cached. Specifically, this means that
  756
+:ref:`limiting the queryset <limiting-querysets>` using an array slice or an
  757
+index will not populate the cache.
  758
+
  759
+For example, repeatedly getting a certain index in a queryset object will query
  760
+the database each time::
  761
+
  762
+    >>> queryset = Entry.objects.all()
  763
+    >>> print queryset[5] # Queries the database
  764
+    >>> print queryset[5] # Queries the database again
  765
+
  766
+However, if the entire queryset has already been evaluated, the cache will be
  767
+checked instead::
  768
+
  769
+    >>> queryset = Entry.objects.all()
  770
+    >>> [entry for entry in queryset] # Queries the database
  771
+    >>> print queryset[5] # Uses cache
  772
+    >>> print queryset[5] # Uses cache
  773
+
  774
+Here are some examples of other actions that will result in the entire queryset
  775
+being evaluated and therefore populate the cache::
  776
+
  777
+    >>> [entry for entry in queryset]
  778
+    >>> bool(queryset)
  779
+    >>> entry in queryset
  780
+    >>> list(queryset)
  781
+
  782
+.. note::
  783
+
  784
+    Simply printing the queryset will not populate the cache. This is because
  785
+    the call to ``__repr__()`` only returns a slice of the entire queryset.
  786
+
750 787
 .. _complex-lookups-with-q:
751 788
 
752 789
 Complex lookups with Q objects

0 notes on commit 8365d76

Please sign in to comment.
Something went wrong with that request. Please try again.