Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#19352 closed Cleanup/optimization (fixed)

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

Reported by: colinkeenan Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords: relationships
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Attachments (1)

19352.diff (1.6 KB ) - added by Tim Graham 11 years ago.

Download all attachments as: .zip

Change History (4)

by Tim Graham, 11 years ago

Attachment: 19352.diff added

comment:1 by Tim Graham, 11 years ago

Has patch: set
Triage Stage: UnreviewedAccepted

comment:2 by Tim Graham <timograham@…>, 11 years ago

Resolution: fixed
Status: newclosed

In ba2adc9c05aa343b58d087a81d9dc84f82b32790:

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

Thanks colinkeenan for the suggestion.

comment:3 by Tim Graham <timograham@…>, 11 years ago

In 931b0f8ccd883630a85871f9482d72986a41f828:

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

Thanks colinkeenan for the suggestion.

Backport of ba2adc9c05 from master

Note: See TracTickets for help on using tickets.
Back to Top