From bc05547cd8c1dd511c6b6a6c873a1bc63417b111 Mon Sep 17 00:00:00 2001 From: Simon Charette Date: Wed, 9 Jan 2019 17:52:36 -0500 Subject: Fixed #28658 -- Added DISTINCT handling to the Aggregate class. --- docs/ref/models/expressions.txt | 19 ++++++++++++++++++- docs/releases/2.2.txt | 7 +++++++ 2 files changed, 25 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 7a358a5ce8..2413952228 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -373,7 +373,7 @@ some complex computations:: The ``Aggregate`` API is as follows: -.. class:: Aggregate(*expressions, output_field=None, filter=None, **extra) +.. class:: Aggregate(*expressions, output_field=None, distinct=False, filter=None, **extra) .. attribute:: template @@ -392,6 +392,14 @@ The ``Aggregate`` API is as follows: Defaults to ``True`` since most aggregate functions can be used as the source expression in :class:`~django.db.models.expressions.Window`. + .. attribute:: allow_distinct + + .. versionadded:: 2.2 + + A class attribute determining whether or not this aggregate function + allows passing a ``distinct`` keyword argument. If set to ``False`` + (default), ``TypeError`` is raised if ``distinct=True`` is passed. + The ``expressions`` positional arguments can include expressions or the names of model fields. They will be converted to a string and used as the ``expressions`` placeholder within the ``template``. @@ -409,6 +417,11 @@ should define the desired ``output_field``. For example, adding an ``IntegerField()`` and a ``FloatField()`` together should probably have ``output_field=FloatField()`` defined. +The ``distinct`` argument determines whether or not the aggregate function +should be invoked for each distinct value of ``expressions`` (or set of +values, for multiple ``expressions``). The argument is only supported on +aggregates that have :attr:`~Aggregate.allow_distinct` set to ``True``. + 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. @@ -416,6 +429,10 @@ and :ref:`filtering-on-annotations` for example usage. The ``**extra`` kwargs are ``key=value`` pairs that can be interpolated into the ``template`` attribute. +.. versionadded:: 2.2 + + The ``allow_distinct`` attribute and ``distinct`` argument were added. + Creating your own Aggregate Functions ------------------------------------- diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt index c8515d5ba6..150fe413db 100644 --- a/docs/releases/2.2.txt +++ b/docs/releases/2.2.txt @@ -239,6 +239,13 @@ Models * Added SQLite support for the :class:`~django.db.models.StdDev` and :class:`~django.db.models.Variance` functions. +* The handling of ``DISTINCT`` aggregation is added to the + :class:`~django.db.models.Aggregate` class. Adding :attr:`allow_distinct = + True ` as a class attribute on + ``Aggregate`` subclasses allows a ``distinct`` keyword argument to be + specified on initialization to ensure that the aggregate function is only + called for each distinct value of ``expressions``. + Requests and Responses ~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.3