Spanning relationship backwards when related_name is used.

[Nat S Dunn]

Under ​https://docs.djangoproject.com/en/3.0/topics/db/queries/#lookups-that-span-relationships, the documentation says:

It works backwards, too. To refer to a “reverse” relationship, use the lowercase name of the model.

This works only if the name of that relationship hasn't been changed with related_name.

I suggest updating the doc to read:

It works backwards, too. To refer to a “reverse” relationship, use the lowercase name of the model, unless you have used related_name to override the name of the relationship, in which case you should use the related_name you have set.

[Carlton Gibson]

OK, yes. Good spot.

The docs should probably cross-reference ​https://docs.djangoproject.com/en/3.0/topics/db/queries/#following-relationships-backward related_query_name here.

At the least it's lowercased + _set, so correcting the examples to match the sample models at the top would probably also ease confusion.

​PR

Update: It's the lookup, rather than the reverse descriptor that's in play here so it's related_query_name that's really in play.

...unless you have used related_name to override the name of the relationship, in which case you should use the related_name you have set,

...unless you set related_query_name... — and so on. I'm inclined towards just adding a , "By default, ... " 🤔

[GitHub <noreply@…>]

In 5af17ba:

Fixed #31591 -- Clarified "reverse" lookup name in making queries docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 844e0591:

[3.1.x] Fixed #31591 -- Clarified "reverse" lookup name in making queries docs.

Backport of 5af17babb0f895cf129fdeee92548d2ac12e78e2 from master