Ticket #20513: 20513.diff

docs/topics/db/queries.txt

@@ -747 +747 @@
     >>> print([p.headline for p in queryset]) # Evaluate the query set.
     >>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.
 
+When querysets are not cached
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Querysets do not always cache their results.  When evaluating only *part* of the queryset, the cache is checked, but if it is not present then the items returned are not cached.
+
+Specifically, this means that :ref:`limiting the queryset <limiting-querysets>` using an array slice or an index will not populate the cache.
+
+For example, repeatedly getting a certain index in a queryset object will requery the database each time::
+
+    >>> queryset = Entry.objects.all()
+    >>> print queryset[5] # Queries the database
+    >>> print queryset[5] # Queries the database again
+
+However, if the entire queryset has already been evaluated, the cache will be checked instead::
+
+    >>> queryset = Entry.objects.all()
+    >>> [entry for entry in queryset] # Queries the database 
+    >>> print queryset[5] # Uses cache
+    >>> print queryset[5] # Uses cache
+
+.. note::
+
+    Simply printing the queryset will not populate the cache.  This is because the call to ``__repr__()`` only returns a slice of the entire Queryset.
+
+Examples of actions that will populate the cache::
+
+    >>> [entry for entry in queryset]
+    >>> bool(queryset)
+    >>> entry in queryset
+    >>> list(queryset)
+
 .. _complex-lookups-with-q:
 
 Complex lookups with Q objects