Функции агрегирования, специфичные для 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()

Устарело начиная с версии 4.0: Если нет строк и default не указан, ArrayAgg возвращает пустой список вместо None. Это поведение устарело и будет удалено в Django 5.0. Если вам нужно это, явно установите default в Value([]).

BitAnd

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

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

BitOr

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

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

BitXor

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

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

BoolAnd

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

Возвращает True, если все входные значения 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 если хотя бы одно входное значение 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}
]}]>

Устарело начиная с версии 4.0: Если нет строк и default не указан, JSONBAgg возвращает пустой список вместо None. Это поведение устарело и будет удалено в Django 5.0. Если вам нужно это, явно установите 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'
}]>

Устарело начиная с версии 4.0: Если нет строк и default не указан, StringAgg возвращает пустую строку вместо None. Это поведение устарело и будет удалено в Django 5.0. Если вам нужно это, явно установите 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}