Clarify the behavior difference between order_by() and Meta.ordering in GROUP BY queries

[Wouter]

Today I hunted an ordering bug. I have a model with ordering = ['name']

And in a view I use:
queryset.annotate(used_by=Count('somerelation')) which drops the order_by.

However the documentation for a aggregation states: ​https://docs.djangoproject.com/en/5.2/topics/db/aggregation/ that:
Django never removes ordering constraints that you have specified.

But then I saw the changelog for version. 2.2. Which explicitly states:

A model’s Meta.ordering affecting GROUP BY queries (such as .annotate().values()) is a common source of confusion. Such queries now issue a deprecation warning with the advice to add an order_by() to retain the current query. Meta.ordering will be ignored in such queries starting in Django 3.1.

Where do I find this information in the current documentation? I think this information is currently missing.

[Jacob Walls]

The ​current documentation only discusses the effect of performing a GROUP BY query after a queryset with .order_by(), but I agree that from this you cannot deduce the effect of doing the same on a model with Meta.ordering, which you might assume acts the same (especially given the "Django never..." wording you quote).

Clarifying that note would be welcome. Would you like to submit a PR?

[Jacob Walls]

I just happened to bump into this ​additional language:

Similarly, if you use a values() query to restrict the columns selected, the columns used in any order_by() (or default model ordering) will still be involved and may affect uniqueness of the results.

Might want to clarify that one also?

[Varun Kasyap Pentamaraju]

I would like to work on this and raise PR, Thanks

[Varun Kasyap Pentamaraju]

created PR ​https://github.com/django/django/pull/20001/

[Wouter]

The patches look okay to me.
What still is difficult to grasp is why order_by 'always' works if applied explicitly, but using ordering does not.

[Varun Kasyap Pentamaraju]

1)Changed from "or" to "and"
2)Used admonition instead of note
3)Better English

[Varun Kasyap Pentamaraju]

1) reversed order of values() and annotate()
2) reverted querysets.txt

[Jacob Walls <jacobtylerwalls@…>]

In 7e765a6:

Fixed #36686 -- Clarified Meta.ordering is ignored in GROUP BY queries.

[Jacob Walls <jacobtylerwalls@…>]

In 37b5dced:

[6.0.x] Fixed #36686 -- Clarified Meta.ordering is ignored in GROUP BY queries.

Backport of 7e765a68598b2b798e49bf1f4b431a7bcac085a4 from main.

[Jacob Walls <jacobtylerwalls@…>]

In edec3e59:

[5.2.x] Fixed #36686 -- Clarified Meta.ordering is ignored in GROUP BY queries.

Backport of 7e765a68598b2b798e49bf1f4b431a7bcac085a4 from main.