Aggregation functions¶
Django provides the following aggregation functions in the django.db.models
module. For details on how to use these aggregate functions, see the topic guide on aggregation. See the Aggregate
documentation to learn how to create your aggregates.
Warning
SQLite can’t handle aggregation on date/time fields out of the box. This is because there are no native date/time fields in SQLite and Django currently emulates these features using a text field. Attempts to use aggregation on date/time fields in SQLite will raise NotImplementedError
.
Note
Aggregation functions return None
when used with an empty QuerySet
. For example, the Sum
aggregation function returns None
instead of 0
if the QuerySet
contains no entries. An exception is Count
, which does return 0
if the QuerySet
is empty.
All aggregates have the following parameters in common:
expression
¶
A string that references a field on the model, or a query expression.
output_field
¶
An optional argument that represents the model field of the return value
Note
When combining multiple field types, Django can only determine the output_field
if all fields are of the same type. Otherwise, you must provide the output_field
yourself.
filter
¶
New in Django 2.0.
An optional Q object
that’s used to filter the rows that are aggregated.
See Conditional aggregation and Filtering on annotations for example usage.
**extra
¶
Keyword arguments that can provide extra context for the SQL generated by the aggregate.
Avg
¶
class Avg
(expression, output_field=FloatField(), filter=None, **extra)[source]¶
Returns the mean value of the given expression, which must be numeric unless you specify a different output_field
.
- Default alias:
<field>__avg
- Return type:
float
(or the type of whateveroutput_field
is specified)
Count
¶
class Count
(expression, distinct=False, filter=None, **extra)[source]¶
Returns the number of objects that are related through the provided expression.
- Default alias:
<field>__count
- Return type:
int
Has one optional argument:
distinct
¶
If distinct=True
, the count will only include unique instances. This is the SQL equivalent of COUNT(DISTINCT <field>)
. The default value is False
.
Max
¶
class Max
(expression, output_field=None, filter=None, **extra)[source]¶
Returns the maximum value of the given expression.
- Default alias:
<field>__max
- Return type: same as input field, or
output_field
if supplied
Min
¶
class Min
(expression, output_field=None, filter=None, **extra)[source]¶
Returns the minimum value of the given expression.
- Default alias:
<field>__min
- Return type: same as input field, or
output_field
if supplied
StdDev
¶
class StdDev
(expression, sample=False, filter=None, **extra)[source]¶
Returns the standard deviation of the data in the provided expression.
- Default alias:
<field>__stddev
- Return type:
float
Has one optional argument:
sample
¶
By default, StdDev
returns the population standard deviation. However, if sample=True
, the return value will be the sample standard deviation.
SQLite
SQLite doesn’t provide StdDev
out of the box. An implementation is available as an extension module for SQLite. Consult the SQlite documentation for instructions on obtaining and installing this extension.
Sum
¶
class Sum
(expression, output_field=None, filter=None, **extra)[source]¶
Computes the sum of all values of the given expression.
- Default alias:
<field>__sum
- Return type: same as input field, or
output_field
if supplied
Variance
¶
class Variance
(expression, sample=False, filter=None, **extra)[source]¶
Returns the variance of the data in the provided expression.
- Default alias:
<field>__variance
- Return type:
float
Has one optional argument:
sample
¶
By default, Variance
returns the population variance. However, if sample=True
, the return value will be the sample variance.
SQLite
SQLite doesn’t provide Variance
out of the box. An implementation is available as an extension module for SQLite. Consult the SQlite documentation for instructions on obtaining and installing this extension.