#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?
Change History (7)
comment:1 by , 3 years ago
comment:2 by , 3 years ago
Summary: | Meaning of empty_result_set_value documentation → Clarify Aggregate.empty_result_set_value docs. |
---|---|
Triage Stage: | Unreviewed → Accepted |
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: 418 418 419 419 .. versionadded:: 4.0 420 420 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. 424 423 425 424 The ``expressions`` positional arguments can include expressions, transforms of 426 425 the model field, or the names of model fields. They will be converted to a
comment:3 by , 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 , 3 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
Triage Stage: | Accepted → Ready for checkin |
Looking at 9f3cce172f6913c5ac74272fa5fc07f847b4e112 where it was introduced, the language seems to resemble a code comment explaining why
Aggregate_aggregate_value
is set toNone
. 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).