Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #9390 -- Restored some documentation about select_related() tha…

…t was

accidentally lost in the docs refactor.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@9256 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 9900c87161279de20760f53b45076d0f216632a2 1 parent 92a6c14
Malcolm Tredinnick authored October 24, 2008

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

  1. 41  docs/ref/models/querysets.txt
41  docs/ref/models/querysets.txt
@@ -511,8 +511,8 @@ related ``Person`` *and* the related ``City``::
511 511
     p = b.author         # Hits the database.
512 512
     c = p.hometown       # Hits the database.
513 513
 
514  
-Note that ``select_related()`` does not follow foreign keys that have
515  
-``null=True``.
  514
+Note that, by default, ``select_related()`` does not follow foreign keys that
  515
+have ``null=True``.
516 516
 
517 517
 Usually, using ``select_related()`` can vastly improve performance because your
518 518
 app can avoid many database calls. However, in situations with deeply nested
@@ -527,9 +527,44 @@ follow::
527 527
     p = b.author         # Doesn't hit the database.
528 528
     c = p.hometown       # Requires a database call.
529 529
 
  530
+Sometimes you only want to access specific models that are related to your root
  531
+model, not all of the related models. In these cases, you can pass the related
  532
+field names to ``select_related()`` and it will only follow those relations.
  533
+You can even do this for models that are more than one relation away by
  534
+separating the field names with double underscores, just as for filters. For
  535
+example, if you have this model::
  536
+
  537
+    class Room(models.Model):
  538
+        # ...
  539
+        building = models.ForeignKey(...)
  540
+
  541
+    class Group(models.Model):
  542
+        # ...
  543
+        teacher = models.ForeignKey(...)
  544
+        room = models.ForeignKey(Room)
  545
+        subject = models.ForeignKey(...)
  546
+
  547
+...and you only needed to work with the ``room`` and ``subject`` attributes,
  548
+you could write this::
  549
+
  550
+    g = Group.objects.select_related('room', 'subject')
  551
+
  552
+This is also valid::
  553
+
  554
+    g = Group.objects.select_related('room__building', 'subject')
  555
+
  556
+...and would also pull in the ``building`` relation.
  557
+
  558
+You can only refer to ``ForeignKey`` relations in the list of fields passed to
  559
+``select_related``. You *can* refer to foreign keys that have ``null=True``
  560
+(unlike the default ``select_related()`` call). It's an error to use both a
  561
+list of fields and the ``depth`` parameter in the same ``select_related()``
  562
+call, since they are conflicting options.
  563
+
530 564
 .. versionadded:: 1.0
531 565
 
532  
-The ``depth`` argument is new in Django version 1.0.
  566
+Both the ``depth`` argument and the ability to specify field names in the call
  567
+to ``select_related()`` are new in Django version 1.0.
533 568
 
534 569
 ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
535 570
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0 notes on commit 9900c87

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