Commit ab07a9b1 authored by Malcolm Tredinnick's avatar Malcolm Tredinnick
Browse files

Added a clarification to the docs about filtering across nullable intermediate 

models with a NULL entry. I'm not brilliantly happy with the description
(it's too long for such an edge case, for a start), but it gets the intent across. Refs #8025.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8141 bcc190cf-cafb-0310-a4f2-bffc1f526a37
parent a14fc400

docs/db-api.txt

+22 −0
Original line number Diff line number Diff line
@@ -1676,6 +1676,28 @@ whose ``headline`` contains ``'Lennon'``:: 


    Blog.objects.filter(entry__headline__contains='Lennon')



If you are filtering across multiple relationships and one of the intermediate

models doesn't have a value that meets the filter condition, Django will treat

it as if there is an empty (all values are ``NULL``), but valid, object there.

All this means is that no error will be raised. For example, in this filter::



    Blog.objects.filter(entry__author__name='Lennon')



(if there was a related ``Author`` model), if there was no ``author``

associated with an entry, it would be treated as if there was also no ``name``

attached, rather than raising an error because of the missing ``author``.

Usually this is exactly what you want to have happen. The only case where it

might be confusing is if you are using ``isnull``. Thus::



    Blog.objects.filter(entry__author__name__isnull=True)



will return ``Blog`` objects that have an empty ``name`` on the ``author`` and

also those which have an empty ``author`` on the ``entry``. If you don't want

those latter objects, you could write::



    Blog.objetcs.filter(entry__author__isnull=False,

            entry__author__name__isnull=True)



Spanning multi-valued relationships

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~