id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
19352	'Spanning multi-valued relationships' needs a less abstract example	colinkeenan	nobody	"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."	Cleanup/optimization	closed	Documentation	dev	Normal	fixed	relationships		Accepted	1	0	0	0	0	0