From ab07a9b19ffdb19196c167469bd54c3fcb2110a2 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Tue, 29 Jul 2008 23:09:54 +0000 Subject: [PATCH] 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 --- docs/db-api.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/db-api.txt b/docs/db-api.txt index a8d6a011e3..f62d5c6d57 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~