diff options
| author | Nick Pope <nick@nickpope.me.uk> | 2021-06-30 00:08:27 +0100 |
|---|---|---|
| committer | Mariusz Felisiak <felisiak.mariusz@gmail.com> | 2021-07-19 13:41:16 +0200 |
| commit | fee87345967b3d917b618533585076cbfa43451b (patch) | |
| tree | 202561eec2284ce1bd3ae4793d32ac346b068848 /docs | |
| parent | 501a8db46595b2d5b99c1d3b1146a832f43cdf1c (diff) | |
Refs #10929 -- Deprecated forced empty result value for PostgreSQL aggregates.
This deprecates forcing a return value for ArrayAgg, JSONBAgg, and
StringAgg when there are no rows in the query. Now that we have a
``default`` argument for aggregates, we want to revert to returning the
default of ``None`` which most aggregate functions return and leave it
up to the user to decide what they want to be returned by default.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 4 | ||||
| -rw-r--r-- | docs/ref/contrib/postgres/aggregates.txt | 21 | ||||
| -rw-r--r-- | docs/releases/4.0.txt | 7 |
3 files changed, 32 insertions, 0 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index c56b875aed..16801e0345 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -30,6 +30,10 @@ details on these changes. * The ``extra_tests`` argument for ``DiscoverRunner.build_suite()`` and ``DiscoverRunner.run_tests()`` will be removed. +* The ``django.contrib.postgres.aggregates.ArrayAgg``, ``JSONBAgg``, and + ``StringAgg`` aggregates will return ``None`` when there are no rows instead + of ``[]``, ``[]``, and ``''`` respectively. + .. _deprecation-removed-in-4.1: 4.1 diff --git a/docs/ref/contrib/postgres/aggregates.txt b/docs/ref/contrib/postgres/aggregates.txt index 61ec86fa44..6d85d5c478 100644 --- a/docs/ref/contrib/postgres/aggregates.txt +++ b/docs/ref/contrib/postgres/aggregates.txt @@ -52,6 +52,13 @@ General-purpose aggregation functions from django.db.models import F F('some_field').desc() + .. deprecated:: 4.0 + + If there are no rows and ``default`` is not provided, ``ArrayAgg`` + returns an empty list instead of ``None``. This behavior is deprecated + and will be removed in Django 5.0. If you need it, explicitly set + ``default`` to ``Value([])``. + ``BitAnd`` ---------- @@ -138,6 +145,13 @@ General-purpose aggregation functions Examples are the same as for :attr:`ArrayAgg.ordering`. + .. deprecated:: 4.0 + + If there are no rows and ``default`` is not provided, ``JSONBAgg`` + returns an empty list instead of ``None``. This behavior is deprecated + and will be removed in Django 5.0. If you need it, explicitly set + ``default`` to ``Value('[]')``. + ``StringAgg`` ------------- @@ -164,6 +178,13 @@ General-purpose aggregation functions Examples are the same as for :attr:`ArrayAgg.ordering`. + .. deprecated:: 4.0 + + If there are no rows and ``default`` is not provided, ``StringAgg`` + returns an empty string instead of ``None``. This behavior is + deprecated and will be removed in Django 5.0. If you need it, + explicitly set ``default`` to ``Value('')``. + Aggregate functions for statistics ================================== diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt index 4122c9b419..244f113c54 100644 --- a/docs/releases/4.0.txt +++ b/docs/releases/4.0.txt @@ -540,6 +540,13 @@ Miscellaneous * The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and :meth:`.DiscoverRunner.run_tests` is deprecated. +* The :class:`~django.contrib.postgres.aggregates.ArrayAgg`, + :class:`~django.contrib.postgres.aggregates.JSONBAgg`, and + :class:`~django.contrib.postgres.aggregates.StringAgg` aggregates will return + ``None`` when there are no rows instead of ``[]``, ``[]``, and ``''`` + respectively in Django 5.0. If you need the previous behavior, explicitly set + ``default`` to ``Value([])``, ``Value('[]')``, or ``Value('')``. + Features removed in 4.0 ======================= |