incorrect/missing documentation for order_by in database api

[Amit Ramon <amit.ramon@…>]

The documentation for order_by in the database api reads the following:

---

To order by a field in a different table, add the other table’s name and a dot, like so:
Entry.objects.order_by('blogs_blog.name', 'headline')

---

However, I believe that in order to be able to sort by a field in another table, (1) the table should be related to each other with a (foreign key) relation to the table we deal with, and (2) one has to use related_objects on this table.

For the given example, the correct code should be, assuming Entry has a ForeignKey to Blog:
Entry.objects.related_objects().order_by('blogs_blog.name', 'headline')

--- Amit

[Malcolm Tredinnick]

It's a given that to order by a related field, the two models have to be related to each other. I don't anybody really believes you can order by a field in an entirely unrelated model, since it just doesn't make sense on any level. Also, there's no such method as related_objects(), but assuming you mean select_related(), that isn't correct.

More generally, though, this particular feature is pretty fragile at the moment and the syntax will be changing slightly soon (when queryset-refactor is merged) and, at that point, it will work as advertised. So I'm going to wontfix this for now, since it's not a feature that people should be encouraged to use and patching the documentation to explain a bug workaround is less optimal than fixing the bug, which is what we're doing at the moment.