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_fieldis 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_fieldif 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_fieldif 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_fieldif 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.