mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-07-24 13:44:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Deprecated depth kwarg on select_related.

Browse source 
This is the start of a deprecation path for the depth kwarg on
select_related. Removing this will allow us to update select_related so
it chains properly and have an API similar to prefetch_related.

Thanks to Marc Tamlyn for spearheading and initial patch.

refs #16855
This commit is contained in:
Preston Holmes 2012-11-02 15:49:29 +00:00
parent 7b57a72d6d
commit 965cc0b1ff
4 changed files with 30 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/ref/models/querysets.txt
View file

@ -676,21 +676,12 @@ Note that, by default, ``select_related()`` does not follow foreign keys that
have ``null=True``.
Usually, using ``select_related()`` can vastly improve performance because your
app can avoid many database calls. However, in situations with deeply nested
sets of relationships ``select_related()`` can sometimes end up following "too
many" relations, and can generate queries so large that they end up being slow.
app can avoid many database calls. However, there are times you are only
interested in specific related models, or have deeply nested sets of
relationships, and in these cases ``select_related()`` can can be optimized by
explicitly passing the related field names you are interested in. Only
the specified relations will be followed.
In these situations, you can use the ``depth`` argument to ``select_related()``
to control how many "levels" of relations ``select_related()`` will actually
follow::
b = Book.objects.select_related(depth=1).get(id=4)
p = b.author # Doesn't hit the database.
c = p.hometown # Requires a database call.
Sometimes you only want to access specific models that are related to your root
model, not all of the related models. In these cases, you can pass the related
field names to ``select_related()`` and it will only follow those relations.
You can even do this for models that are more than one relation away by
separating the field names with double underscores, just as for filters. For
example, if you have this model::
@ -730,6 +721,17 @@ You can also refer to the reverse direction of a
is defined. Instead of specifying the field name, use the :attr:`related_name
<django.db.models.ForeignKey.related_name>` for the field on the related object.
.. deprecated:: 1.5
The ``depth`` parameter to ``select_related()`` has been deprecated. You
should replace it with the use of the ``(*fields)`` listing specific
related fields instead as documented above.
A depth limit of relationships to follow can also be specified::
b = Book.objects.select_related(depth=1).get(id=4)
p = b.author # Doesn't hit the database.
c = p.hometown # Requires a database call.
A :class:`~django.db.models.OneToOneField` is not traversed in the reverse
direction if you are performing a depth-based ``select_related()`` call.