Opened 3 years ago

Closed 3 years ago

Last modified 3 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: master
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 timo 3 years ago.

Download all attachments as: .zip

Change History (4)

Changed 3 years ago by timo

comment:1 Changed 3 years ago by timo

  • Has patch set
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 3 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In ba2adc9c05aa343b58d087a81d9dc84f82b32790:

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

Thanks colinkeenan for the suggestion.

comment:3 Changed 3 years ago by 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

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