From 4b977a5d7283e7ca51288cc0ed0860e0004653ca Mon Sep 17 00:00:00 2001 From: Chris Muthig Date: Sun, 22 Dec 2024 16:30:55 +0100 Subject: Fixed #35444 -- Added generic support for Aggregate.order_by. This moves the behaviors of `order_by` used in Postgres aggregates into the `Aggregate` class. This allows for creating aggregate functions that support this behavior across all database engines. This is shown by moving the `StringAgg` class into the shared `aggregates` module and adding support for all databases. The Postgres `StringAgg` class is now a thin wrapper on the new shared `StringAgg` class. Thank you Simon Charette for the review. --- docs/ref/contrib/postgres/aggregates.txt | 2 ++ docs/ref/models/expressions.txt | 21 ++++++++++++++++++++- docs/ref/models/querysets.txt | 19 +++++++++++++++++++ 3 files changed, 41 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/contrib/postgres/aggregates.txt b/docs/ref/contrib/postgres/aggregates.txt index 80c8acf80b..d590eb384f 100644 --- a/docs/ref/contrib/postgres/aggregates.txt +++ b/docs/ref/contrib/postgres/aggregates.txt @@ -194,6 +194,8 @@ General-purpose aggregation functions .. class:: StringAgg(expression, delimiter, distinct=False, filter=None, default=None, order_by=()) + .. deprecated:: 6.0 + Returns the input values concatenated into a string, separated by the ``delimiter`` string, or ``default`` if there are no values. diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 6a6356b3bb..c3c9ebba7a 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -448,7 +448,7 @@ some complex computations:: The ``Aggregate`` API is as follows: -.. class:: Aggregate(*expressions, output_field=None, distinct=False, filter=None, default=None, **extra) +.. class:: Aggregate(*expressions, output_field=None, distinct=False, filter=None, default=None, order_by=None, **extra) .. attribute:: template @@ -473,6 +473,15 @@ The ``Aggregate`` API is as follows: allows passing a ``distinct`` keyword argument. If set to ``False`` (default), ``TypeError`` is raised if ``distinct=True`` is passed. + .. attribute:: allow_order_by + + .. versionadded:: 6.0 + + A class attribute determining whether or not this aggregate function + allows passing a ``order_by`` keyword argument. If set to ``False`` + (default), ``TypeError`` is raised if ``order_by`` is passed as a value + other than ``None``. + .. attribute:: empty_result_set_value Defaults to ``None`` since most aggregate functions result in ``NULL`` @@ -491,6 +500,12 @@ The ``filter`` argument takes a :class:`Q object ` that's used to filter the rows that are aggregated. See :ref:`conditional-aggregation` and :ref:`filtering-on-annotations` for example usage. +The ``order_by`` argument behaves similarly to the ``field_names`` input of the +:meth:`~.QuerySet.order_by` function, accepting 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. + The ``default`` argument takes a value that will be passed along with the aggregate to :class:`~django.db.models.functions.Coalesce`. This is useful for specifying a value to be returned other than ``None`` when the queryset (or @@ -499,6 +514,10 @@ grouping) contains no entries. The ``**extra`` kwargs are ``key=value`` pairs that can be interpolated into the ``template`` attribute. +.. versionchanged:: 6.0 + + The ``order_by`` argument was added. + Creating your own Aggregate Functions ------------------------------------- diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 8bf83838c0..06d2086328 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -4046,6 +4046,25 @@ by the aggregate. However, if ``sample=True``, the return value will be the sample variance. +``StringAgg`` +~~~~~~~~~~~~~ + +.. versionadded:: 6.0 + +.. class:: StringAgg(expression, delimiter, output_field=None, distinct=False, filter=None, order_by=None, default=None, **extra) + + Returns the input values concatenated into a string, separated by the + ``delimiter`` string, or ``default`` if there are no values. + + * Default alias: ``__stringagg`` + * Return type: ``string`` or ``output_field`` if supplied. If the + queryset or grouping is empty, ``default`` is returned. + + .. attribute:: delimiter + + A ``Value`` or expression representing the string that should separate + each of the values. For example, ``Value(",")``. + Query-related tools =================== -- cgit v1.3