Функции агрегации, специфичные для PostgreSQL

Эти функции доступны из модуля django.contrib.postgres.aggregates. Более подробное описание приведено в документации PostgreSQL.

>>> SomeModel.objects.aggregate(arr=ArrayAgg("somefield"))
{'arr': [0, 1, 2]}

Функции агрегирования общего назначения

ArrayAgg

class ArrayAgg(expression, distinct=False, filter=None, default=None, ordering=(), **extra)

Возвращает список значений, включая NULL, объединённых в массив, или default если значений нет.

distinct

Необязательный булевый аргумент, определяющий, будут ли значения в массиве уникальными. По умолчанию False.

ordering

Необязательный строковый аргумент имени поля (с необязательным префиксом "-" для указания убывающего порядка) или выражение (или кортеж или список строк и/или выражений), которые определяют порядок элементов в результирующем списке.

Примеры:

"some_field"
"-some_field"
from django.db.models import F

F("some_field").desc()

Изменено в Django 5.0:

В более старых версиях, если нет строк и не указано default, ArrayAgg возвращала пустой список вместо None. Если вам нужно это, явно задайте default в значение Value([]).

BitAnd

class BitAnd(expression, filter=None, default=None, **extra)

Возвращает int битового AND всех ненулевых входных значений или default если все значения NULL.

BitOr

class BitOr(expression, filter=None, default=None, **extra)

Возвращает int битового OR всех ненулевых входных значений или default если все значения NULL.

BitXor

class BitXor(expression, filter=None, default=None, **extra)

Возвращает int битового XOR всех ненулевых входных значений, или default если все значения NULL. Требуется PostgreSQL 14+.

BoolAnd

class BoolAnd(expression, filter=None, default=None, **extra)

Возвращает True, если все входные значения истинные, default если все значения NULL или нет значений, в противном случае False.

Пример использования:

class Comment(models.Model):
    body = models.TextField()
    published = models.BooleanField()
    rank = models.IntegerField()

>>> from django.db.models import Q
>>> from django.contrib.postgres.aggregates import BoolAnd
>>> Comment.objects.aggregate(booland=BoolAnd("published"))
{'booland': False}
>>> Comment.objects.aggregate(booland=BoolAnd(Q(rank__lt=100)))
{'booland': True}

BoolOr

class BoolOr(expression, filter=None, default=None, **extra)

Возвращает True если хотя бы одно входное значение истинно, default если все значения NULL или нет значений, в противном случае False.

Пример использования:

class Comment(models.Model):
    body = models.TextField()
    published = models.BooleanField()
    rank = models.IntegerField()

>>> from django.db.models import Q
>>> from django.contrib.postgres.aggregates import BoolOr
>>> Comment.objects.aggregate(boolor=BoolOr("published"))
{'boolor': True}
>>> Comment.objects.aggregate(boolor=BoolOr(Q(rank__gt=2)))
{'boolor': False}

JSONBAgg

class JSONBAgg(expressions, distinct=False, filter=None, default=None, ordering=(), **extra)

Возвращает входные значения в виде JSON массива или default если значений нет. Вы можете запросить результат, используя key and index lookups.

distinct

Необязательный булевый аргумент, определяющий, будут ли значения в массиве уникальными. По умолчанию False.

ordering

Необязательный строковый аргумент имени поля (с необязательным префиксом "-" для указания убывающего порядка) или выражение (или кортеж или список строк и/или выражений), которые определяют порядок элементов в результирующем списке.

Примеры аналогичны ArrayAgg.ordering.

Пример использования:

class Room(models.Model):
    number = models.IntegerField(unique=True)


class HotelReservation(models.Model):
    room = models.ForeignKey("Room", on_delete=models.CASCADE)
    start = models.DateTimeField()
    end = models.DateTimeField()
    requirements = models.JSONField(blank=True, null=True)

>>> from django.contrib.postgres.aggregates import JSONBAgg
>>> Room.objects.annotate(
...     requirements=JSONBAgg(
...         "hotelreservation__requirements",
...         ordering="-hotelreservation__start",
...     )
... ).filter(requirements__0__sea_view=True).values("number", "requirements")
<QuerySet [{'number': 102, 'requirements': [
    {'parking': False, 'sea_view': True, 'double_bed': False},
    {'parking': True, 'double_bed': True}
]}]>

Изменено в Django 5.0:

В более старых версиях, если нет строк и не указано default, JSONBAgg возвращала пустой список вместо None. Если вам нужно это, явно задайте default в значение Value([]).

StringAgg

class StringAgg(expression, delimiter, distinct=False, filter=None, default=None, ordering=())

Возвращает входные значения, объединённые в строку, разделённые строкой delimiter, или default если значений нет.

delimiter

Обязательный аргумент. Должен быть строкой.

distinct

Необязательный булевый аргумент, определяющий, будут ли объединённые значения уникальными. По умолчанию False.

ordering

Необязательный строковый аргумент имени поля (с необязательным префиксом "-" для указания убывающего порядка) или выражение (или кортеж или список строк и/или выражений), которые определяют порядок элементов в результирующей строке.

Примеры аналогичны ArrayAgg.ordering.

Пример использования:

class Publication(models.Model):
    title = models.CharField(max_length=30)


class Article(models.Model):
    headline = models.CharField(max_length=100)
    publications = models.ManyToManyField(Publication)

>>> article = Article.objects.create(headline="NASA uses Python")
>>> article.publications.create(title="The Python Journal")
<Publication: Publication object (1)>
>>> article.publications.create(title="Science News")
<Publication: Publication object (2)>
>>> from django.contrib.postgres.aggregates import StringAgg
>>> Article.objects.annotate(
...     publication_names=StringAgg(
...         "publications__title",
...         delimiter=", ",
...         ordering="publications__title",
...     )
... ).values("headline", "publication_names")
<QuerySet [{
    'headline': 'NASA uses Python', 'publication_names': 'Science News, The Python Journal'
}]>

Изменено в Django 5.0:

В более старых версиях, если нет строк и не указано default, StringAgg возвращала пустую строку вместо None. Если вам нужно это, явно задайте default в значение Value("").

Функции агрегации для статистики

y и x

Аргументы y и x для всех этих функций могут быть именем поля или выражением, возвращающим числовые данные. Оба обязательны.

Corr

class Corr(y, x, filter=None, default=None)

Возвращает коэффициент корреляции в виде float, или default если нет соответствующих строк.

CovarPop

class CovarPop(y, x, sample=False, filter=None, default=None)

Возвращает ковариацию генеральной совокупности в виде float, или default если нет соответствующих строк.

sample

Необязательный. По умолчанию CovarPop возвращает ковариацию генеральной совокупности. Однако, если sample=True, возвращаемое значение будет ковариацией выборочной совокупности.

RegrAvgX

class RegrAvgX(y, x, filter=None, default=None)

Возвращает среднее значение независимой переменной (sum(x)/N) в виде float, или default если нет соответствующих строк.

RegrAvgY

class RegrAvgY(y, x, filter=None, default=None)

Возвращает среднее значение зависимой переменной (sum(y)/N) в виде float, или default если нет соответствующих строк.

RegrCount

class RegrCount(y, x, filter=None)

Возвращает количество входных строк, в которых оба выражения не NULL.

Примечание

Аргумент default не поддерживается.

RegrIntercept

class RegrIntercept(y, x, filter=None, default=None)

Возвращает значение y-пересечения прямой наименьших квадратов, определяемой (x, y) парами в виде float, или default если нет соответствующих строк.

RegrR2

class RegrR2(y, x, filter=None, default=None)

Возвращает квадрат коэффициента корреляции в виде float, или default если нет соответствующих строк.

RegrSlope

class RegrSlope(y, x, filter=None, default=None)

Возвращает наклон прямой наименьших квадратов, определяемой (x, y) парами в виде float, или default если нет соответствующих строк.

RegrSXX

class RegrSXX(y, x, filter=None, default=None)

Возвращает sum(x^2) - sum(x)^2/N («сумму квадратов» независимой переменной) в виде float, или default если нет совпадающих строк.

RegrSXY

class RegrSXY(y, x, filter=None, default=None)

Возвращает sum(x*y) - sum(x) * sum(y)/N («сумму произведений» независимой и зависимой переменных) в виде float, или default если нет совпадающих строк.

RegrSYY

class RegrSYY(y, x, filter=None, default=None)

Возвращает sum(y^2) - sum(y)^2/N («сумму квадратов» зависимой переменной) в виде float, или default если нет совпадающих строк.

Примеры использования

Мы будем использовать следующую примерную таблицу:

| FIELD1 | FIELD2 | FIELD3 |
|--------|--------|--------|
|    foo |      1 |     13 |
|    bar |      2 | (null) |
|   test |      3 |     13 |

Вот несколько примеров использования агрегационных функций общего назначения:

>>> TestModel.objects.aggregate(result=StringAgg("field1", delimiter=";"))
{'result': 'foo;bar;test'}
>>> TestModel.objects.aggregate(result=ArrayAgg("field2"))
{'result': [1, 2, 3]}
>>> TestModel.objects.aggregate(result=ArrayAgg("field1"))
{'result': ['foo', 'bar', 'test']}

Следующий пример демонстрирует использование статистических агрегационных функций. Основополагающие математические вычисления не будут описываться (вы можете узнать об этом, например, на wikipedia):

>>> TestModel.objects.aggregate(count=RegrCount(y="field3", x="field2"))
{'count': 2}
>>> TestModel.objects.aggregate(
...     avgx=RegrAvgX(y="field3", x="field2"), avgy=RegrAvgY(y="field3", x="field2")
... )
{'avgx': 2, 'avgy': 13}