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

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