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

@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~