Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #20842 and #20845 - Added a note on order_by() and improved pre…

…fetch_related() docs.
  • Loading branch information...
commit e8183a8193ebc80fdc6fef789813c2c0c3615e5c 1 parent 3e0eb2d
Daniele Procida authored August 02, 2013 timgraham committed August 04, 2013

Showing 1 changed file with 67 additions and 36 deletions. Show diff stats Hide diff stats

  1. 103  docs/ref/models/querysets.txt
103  docs/ref/models/querysets.txt
@@ -110,7 +110,7 @@ described here.
110 110
 
111 111
 .. admonition:: You can't share pickles between versions
112 112
 
113  
-    Pickles of QuerySets are only valid for the version of Django that
  113
+    Pickles of ``QuerySets`` are only valid for the version of Django that
114 114
     was used to generate them. If you generate a pickle using Django
115 115
     version N, there is no guarantee that pickle will be readable with
116 116
     Django version N+1. Pickles should not be used as part of a long-term
@@ -298,14 +298,30 @@ Be cautious when ordering by fields in related models if you are also using
298 298
 :meth:`distinct()`. See the note in :meth:`distinct` for an explanation of how
299 299
 related model ordering can change the expected results.
300 300
 
301  
-It is permissible to specify a multi-valued field to order the results by (for
302  
-example, a :class:`~django.db.models.ManyToManyField` field). Normally
303  
-this won't be a sensible thing to do and it's really an advanced usage
304  
-feature. However, if you know that your queryset's filtering or available data
305  
-implies that there will only be one ordering piece of data for each of the main
306  
-items you are selecting, the ordering may well be exactly what you want to do.
307  
-Use ordering on multi-valued fields with care and make sure the results are
308  
-what you expect.
  301
+.. note::
  302
+    It is permissible to specify a multi-valued field to order the results by
  303
+    (for example, a :class:`~django.db.models.ManyToManyField` field, or the
  304
+    reverse relation of a :class:`~django.db.models.ForeignKey` field).
  305
+
  306
+    Consider this case::
  307
+
  308
+         class Event(Model):
  309
+            parent = models.ForeignKey('self', related_name='children')
  310
+            date = models.DateField()
  311
+
  312
+         Event.objects.order_by('children__date')
  313
+
  314
+    Here, there could potentially be multiple ordering data for each ``Event``;
  315
+    each ``Event`` with multiple ``children`` will be returned multiple times
  316
+    into the new ``QuerySet`` that ``order_by()`` creates. In other words,
  317
+    using ``order_by()`` on the ``QuerySet`` could return more items than you
  318
+    were working on to begin with - which is probably neither expected nor
  319
+    useful.
  320
+
  321
+    Thus, take care when using multi-valued field to order the results. **If**
  322
+    you can be sure that there will only be one ordering piece of data for each
  323
+    of the items you're ordering, this approach should not present problems. If
  324
+    not, make sure the results are what you expect.
309 325
 
310 326
 There's no way to specify whether ordering should be case sensitive. With
311 327
 respect to case-sensitivity, Django will order results however your database
@@ -386,7 +402,7 @@ field names, the database will only compare the specified field names.
386 402
 
387 403
 .. note::
388 404
     When you specify field names, you *must* provide an ``order_by()`` in the
389  
-    QuerySet, and the fields in ``order_by()`` must start with the fields in
  405
+    ``QuerySet``, and the fields in ``order_by()`` must start with the fields in
390 406
     ``distinct()``, in the same order.
391 407
 
392 408
     For example, ``SELECT DISTINCT ON (a)`` gives you the first row for each
@@ -787,8 +803,8 @@ stop the deluge of database queries that is caused by accessing related objects,
787 803
 but the strategy is quite different.
788 804
 
789 805
 ``select_related`` works by creating a SQL join and including the fields of the
790  
-related object in the SELECT statement. For this reason, ``select_related`` gets
791  
-the related objects in the same database query. However, to avoid the much
  806
+related object in the ``SELECT`` statement. For this reason, ``select_related``
  807
+gets the related objects in the same database query. However, to avoid the much
792 808
 larger result set that would result from joining across a 'many' relationship,
793 809
 ``select_related`` is limited to single-valued relationships - foreign key and
794 810
 one-to-one.
@@ -817,39 +833,54 @@ For example, suppose you have these models::
817 833
             return u"%s (%s)" % (self.name, u", ".join([topping.name
818 834
                                                         for topping in self.toppings.all()]))
819 835
 
820  
-and run this code::
  836
+and run::
821 837
 
822 838
     >>> Pizza.objects.all()
823 839
     [u"Hawaiian (ham, pineapple)", u"Seafood (prawns, smoked salmon)"...
824 840
 
825  
-The problem with this code is that it will run a query on the Toppings table for
826  
-**every** item in the Pizza ``QuerySet``.  Using ``prefetch_related``, this can
827  
-be reduced to two:
  841
+The problem with this is that every time ``Pizza.__unicode__()`` asks for
  842
+``self.toppings.all()`` it has to query the database, so
  843
+``Pizza.objects.all()`` will run a query on the Toppings table for **every**
  844
+item in the Pizza ``QuerySet``.
  845
+
  846
+We can reduce to just two queries using ``prefetch_related``:
828 847
 
829 848
     >>> Pizza.objects.all().prefetch_related('toppings')
830 849
 
831  
-All the relevant toppings will be fetched in a single query, and used to make
832  
-``QuerySets`` that have a pre-filled cache of the relevant results. These
833  
-``QuerySets`` are then used in the ``self.toppings.all()`` calls.
  850
+This implies a ``self.toppings.all()`` for each ``Pizza``; now each time
  851
+``self.toppings.all()`` is called, instead of having to go to the database for
  852
+the items, it will find them in a prefetched ``QuerySet`` cache that was
  853
+populated in a single query.
  854
+
  855
+That is, all the relevant toppings will have been fetched in a single query,
  856
+and used to make ``QuerySets`` that have a pre-filled cache of the relevant
  857
+results; these ``QuerySets`` are then used in the ``self.toppings.all()`` calls.
  858
+
  859
+The additional queries in ``prefetch_related()`` are executed after the
  860
+``QuerySet`` has begun to be evaluated and the primary query has been executed.
834 861
 
835  
-The additional queries are executed after the QuerySet has begun to be evaluated
836  
-and the primary query has been executed. Note that the result cache of the
837  
-primary QuerySet and all specified related objects will then be fully loaded
838  
-into memory, which is often avoided in other cases - even after a query has been
839  
-executed in the database, QuerySet normally tries to make uses of chunking
840  
-between the database to avoid loading all objects into memory before you need
841  
-them.
  862
+Note that the result cache of the primary ``QuerySet`` and all specified related
  863
+objects will then be fully loaded into memory. This changes the typical
  864
+behavior of ``QuerySets``, which normally try to avoid loading all objects into
  865
+memory before they are needed, even after a query has been executed in the
  866
+database.
  867
+
  868
+.. note::
842 869
 
843  
-Also remember that, as always with QuerySets, any subsequent chained methods
844  
-which imply a different database query will ignore previously cached results,
845  
-and retrieve data using a fresh database query. So, if you write the following:
  870
+    Remember that, as always with ``QuerySets``, any subsequent chained methods
  871
+    which imply a different database query will ignore previously cached
  872
+    results, and retrieve data using a fresh database query. So, if you write
  873
+    the following:
846 874
 
847  
-    >>> pizzas = Pizza.objects.prefetch_related('toppings')
848  
-    >>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]
  875
+        >>> pizzas = Pizza.objects.prefetch_related('toppings')
  876
+        >>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]
849 877
 
850  
-...then the fact that ``pizza.toppings.all()`` has been prefetched will not help
851  
-you - in fact it hurts performance, since you have done a database query that
852  
-you haven't used. So use this feature with caution!
  878
+    ...then the fact that ``pizza.toppings.all()`` has been prefetched will not
  879
+    help you. The ``prefetch_related('toppings')`` implied
  880
+    ``pizza.toppings.all()``, but ``pizza.toppings.filter()`` is a new and
  881
+    different query. The prefetched cache can't help here; in fact it hurts
  882
+    performance, since you have done a database query that you haven't used. So
  883
+    use this feature with caution!
853 884
 
854 885
 You can also use the normal join syntax to do related fields of related
855 886
 fields. Suppose we have an additional model to the example above::
@@ -902,7 +933,7 @@ additional queries on the ``ContentType`` table if the relevant rows have not
902 933
 already been fetched.
903 934
 
904 935
 ``prefetch_related`` in most cases will be implemented using a SQL query that
905  
-uses the 'IN' operator. This means that for a large QuerySet a large 'IN' clause
  936
+uses the 'IN' operator. This means that for a large ``QuerySet`` a large 'IN' clause
906 937
 could be generated, which, depending on the database, might have performance
907 938
 problems of its own when it comes to parsing or executing the SQL query. Always
908 939
 profile for your use case!
@@ -1273,7 +1304,7 @@ raw
1273 1304
 
1274 1305
 Takes a raw SQL query, executes it, and returns a
1275 1306
 ``django.db.models.query.RawQuerySet`` instance. This ``RawQuerySet`` instance
1276  
-can be iterated over just like an normal QuerySet to provide object instances.
  1307
+can be iterated over just like an normal ``QuerySet`` to provide object instances.
1277 1308
 
1278 1309
 See the :ref:`executing-raw-queries` for more information.
1279 1310
 

0 notes on commit e8183a8

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