'Spanning multi-valued relationships' needs a less abstract example

[colinkeenan]

In ​https://docs.djangoproject.com/en/dev/topics/db/queries/, there is an example that is supposed to clarify, but really doesn't because it's too abstract in the end. Here is the relevant text:

That may sound a bit confusing, so hopefully an example will clarify. To select all blogs that contain entries with both "Lennon" in the headline and that were published in 2008 (the same entry satisfying both conditions), we would write:

Blog.objects.filter(entry__headline__contains='Lennon',
        entry__pub_date__year=2008)

To select all blogs that contain an entry with "Lennon" in the headline as well as an entry that was published in 2008, we would write:

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

In this second example, the first filter restricted the queryset to all those blogs linked to that particular type of entry. The second filter restricted the set of blogs further to those that are also linked to the second type of entry. The entries select by the second filter may or may not be the same as the entries in the first filter. We are filtering the Blog items with each filter statement, not the Entry items.

The problem is in the last paragraph (italics are mine) which is all of a sudden very abstract making the example impossible to follow unless the reader starts making up there own examples. I suggest that before discussing the example in the abstract, give an actual example. Something like...

Suppose there is only one blog that had any entries containing 'Lennon' and also entries from 2008, but that none of the entries from 2008 contained 'Lennon'. Then, the first query would not return any blogs, but the second query would return that one blog.

[Tim Graham <timograham@…>]

In ba2adc9c05aa343b58d087a81d9dc84f82b32790:

Fixed #19352 - Added an example in the QuerySet docs.

Thanks colinkeenan for the suggestion.

[Tim Graham <timograham@…>]

In 931b0f8ccd883630a85871f9482d72986a41f828:

[1.5.X] Fixed #19352 - Added an example in the QuerySet docs.

Thanks colinkeenan for the suggestion.

Backport of ba2adc9c05 from master