diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/db-api.txt | 22 |
1 files changed, 22 insertions, 0 deletions
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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |