mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 19:08:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Refs #35444 -- Deprecated contrib.postgres aggregates ordering for order_by.

Browse source 
Aligns the argument with SQL standards already used in Window.order_by and
sets up for adding support to Aggregate.
This commit is contained in:
Chris Muthig 2024-07-06 10:44:11 -06:00 • committed by Sarah Boyce
parent 46b3e7dd8c
commit d734f1651c
7 changed files with 137 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/ref/contrib/postgres/aggregates.txt
View file

@ -30,7 +30,7 @@ General-purpose aggregation functions
``ArrayAgg``
------------
.. class:: ArrayAgg(expression, distinct=False, filter=None, default=None, ordering=(), **extra)
.. class:: ArrayAgg(expression, distinct=False, filter=None, default=None, order_by=(), **extra)
Returns a list of values, including nulls, concatenated into an array, or
``default`` if there are no values.
@ -40,7 +40,9 @@ General-purpose aggregation functions
An optional boolean argument that determines if array values
will be distinct. Defaults to ``False``.
.. attribute:: ordering
.. attribute:: order_by
.. versionadded:: 5.2
An optional string of a field name (with an optional ``"-"`` prefix
which indicates descending order) or an expression (or a tuple or list
@ -55,6 +57,11 @@ General-purpose aggregation functions
F("some_field").desc()
.. deprecated:: 5.2
The ``ordering`` keyword argument is deprecated. Use
:attr:`ArrayAgg.order_by` instead.
``BitAnd``
----------
@ -130,7 +137,7 @@ General-purpose aggregation functions
``JSONBAgg``
------------
.. class:: JSONBAgg(expressions, distinct=False, filter=None, default=None, ordering=(), **extra)
.. class:: JSONBAgg(expressions, distinct=False, filter=None, default=None, order_by=(), **extra)
Returns the input values as a ``JSON`` array, or ``default`` if there are
no values. You can query the result using :lookup:`key and index lookups
@ -141,14 +148,16 @@ General-purpose aggregation functions
An optional boolean argument that determines if array values will be
distinct. Defaults to ``False``.
.. attribute:: ordering
.. attribute:: order_by
.. versionadded:: 5.2
An optional string of a field name (with an optional ``"-"`` prefix
which indicates descending order) or an expression (or a tuple or list
of strings and/or expressions) that specifies the ordering of the
elements in the result list.
Examples are the same as for :attr:`ArrayAgg.ordering`.
Examples are the same as for :attr:`ArrayAgg.order_by`.
Usage example::
@ -168,7 +177,7 @@ General-purpose aggregation functions
>>> Room.objects.annotate(
... requirements=JSONBAgg(
... "hotelreservation__requirements",
... ordering="-hotelreservation__start",
... order_by="-hotelreservation__start",
... )
... ).filter(requirements__0__sea_view=True).values("number", "requirements")
<QuerySet [{'number': 102, 'requirements': [
@ -176,10 +185,15 @@ General-purpose aggregation functions
{'parking': True, 'double_bed': True}
]}]>
.. deprecated:: 5.2
The ``ordering`` keyword argument is deprecated. Use
:attr:`JSONBAgg.order_by` instead.
``StringAgg``
-------------
.. class:: StringAgg(expression, delimiter, distinct=False, filter=None, default=None, ordering=())
.. class:: StringAgg(expression, delimiter, distinct=False, filter=None, default=None, order_by=())
Returns the input values concatenated into a string, separated by
the ``delimiter`` string, or ``default`` if there are no values.
@ -193,14 +207,16 @@ General-purpose aggregation functions
An optional boolean argument that determines if concatenated values
will be distinct. Defaults to ``False``.
.. attribute:: ordering
.. attribute:: order_by
.. versionadded:: 5.2
An optional string of a field name (with an optional ``"-"`` prefix
which indicates descending order) or an expression (or a tuple or list
of strings and/or expressions) that specifies the ordering of the
elements in the result string.
Examples are the same as for :attr:`ArrayAgg.ordering`.
Examples are the same as for :attr:`ArrayAgg.order_by`.
Usage example::
@ -224,13 +240,18 @@ General-purpose aggregation functions
... publication_names=StringAgg(
... "publications__title",
... delimiter=", ",
... ordering="publications__title",
... order_by="publications__title",
... )
... ).values("headline", "publication_names")
<QuerySet [{
'headline': 'NASA uses Python', 'publication_names': 'Science News, The Python Journal'
}]>
.. deprecated:: 5.2
The ``ordering`` keyword argument is deprecated. Use
:attr:`StringAgg.order_by` instead.
Aggregate functions for statistics
==================================