Changeset 8141

Timestamp:

07/29/08 18:09:54 (5 months ago)

Author:

mtredinnick

Message:

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.

Files:

• django/trunk/docs/db-api.txt (modified) (1 diff)

django/trunk/docs/db-api.txt

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