Code

Ticket #20513: 20513.diff

File 20513.diff, 1.7 KB (added by seddonym, 14 months ago)
Line 
1diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
2index 39ef2b3..c3cf3c0 100644
3--- a/docs/topics/db/queries.txt
4+++ b/docs/topics/db/queries.txt
5@@ -747,6 +747,37 @@ To avoid this problem, simply save the
6     >>> print([p.headline for p in queryset]) # Evaluate the query set.
7     >>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.
8 
9+When querysets are not cached
10+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
11+
12+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.
13+
14+Specifically, this means that :ref:`limiting the queryset <limiting-querysets>` using an array slice or an index will not populate the cache.
15+
16+For example, repeatedly getting a certain index in a queryset object will requery the database each time::
17+
18+    >>> queryset = Entry.objects.all()
19+    >>> print queryset[5] # Queries the database
20+    >>> print queryset[5] # Queries the database again
21+
22+However, if the entire queryset has already been evaluated, the cache will be checked instead::
23+
24+    >>> queryset = Entry.objects.all()
25+    >>> [entry for entry in queryset] # Queries the database
26+    >>> print queryset[5] # Uses cache
27+    >>> print queryset[5] # Uses cache
28+
29+.. note::
30+
31+    Simply printing the queryset will not populate the cache.  This is because the call to ``__repr__()`` only returns a slice of the entire Queryset.
32+
33+Examples of actions that will populate the cache::
34+
35+    >>> [entry for entry in queryset]
36+    >>> bool(queryset)
37+    >>> entry in queryset
38+    >>> list(queryset)
39+
40 .. _complex-lookups-with-q:
41 
42 Complex lookups with Q objects