Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#33391 closed Cleanup/optimization (fixed)

Clarify Aggregate.empty_result_set_value docs.

Reported by: Claude Paroz Owned by: Mariusz Felisiak
Component: Documentation Version: 4.0
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

While translating the new docs, I struggled to understand the meaning of this sentence about Aggregate.empty_result_set_value:

Override empty_result_set_value to None since most aggregate functions result in NULL when applied to an empty result set.

It's totally possible my limited English prevents me understanding this, in that case, maybe someone may explains that to me?

https://docs.djangoproject.com/en/4.0/ref/models/expressions/#django.db.models.Aggregate.empty_result_set_value

Change History (7)

comment:1 by Tim Graham, 3 years ago

Looking at 9f3cce172f6913c5ac74272fa5fc07f847b4e112 where it was introduced, the language seems to resemble a code comment explaining why Aggregate_aggregate_value is set to None. It's unclear to me if this information is useful to Django users. At the least, it seems a rephrasing is appropriate ("Override" to "Overrides", perhaps).

comment:2 by Mariusz Felisiak, 3 years ago

Summary: Meaning of empty_result_set_value documentationClarify Aggregate.empty_result_set_value docs.
Triage Stage: UnreviewedAccepted

Aggregate.empty_result_set_value defaults to None which is fine for most (all?) aggregates, so I'd clarify this in docs, e.g.:

  • docs/ref/models/expressions.txt

    diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
    index 5ea7f9f0aa..208b810048 100644
    a b The ``Aggregate`` API is as follows:  
    418418
    419419        .. versionadded:: 4.0
    420420
    421         Override :attr:`~django.db.models.Expression.empty_result_set_value` to
    422         ``None`` since most aggregate functions result in ``NULL`` when applied
    423         to an empty result set.
     421        Defaults to ``None`` since most aggregate functions result in ``NULL``
     422        when applied to an empty result set.
    424423
    425424The ``expressions`` positional arguments can include expressions, transforms of
    426425the model field, or the names of model fields. They will be converted to a

comment:3 by Claude Paroz, 3 years ago

Has patch: set

Ah thanks, now I understand (even the original sentence!). The new proposal is a lot better!

comment:4 by Tim Graham, 3 years ago

Owner: changed from nobody to Mariusz Felisiak
Status: newassigned
Triage Stage: AcceptedReady for checkin

comment:5 by Mariusz Felisiak, 3 years ago

comment:6 by GitHub <noreply@…>, 3 years ago

Resolution: fixed
Status: assignedclosed

In 4400d856:

Fixed #33391 -- Clarified Aggregate.empty_result_set_value docs.

comment:7 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In fe59bf2:

[4.0.x] Fixed #33391 -- Clarified Aggregate.empty_result_set_value docs.

Backport of 4400d8568ad5695c46e8de45635a82a27a26b871 from main

Note: See TracTickets for help on using tickets.
Back to Top