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

BoolAnd

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

Возвращает True, если все входные значения истинны, default если все значения нулевые или нет значений, в противном случае 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 если все значения нулевые или нет значений, в противном случае 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

Добавлена в Django 3.2.

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

ordering

Добавлена в Django 3.2.

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

Примеры такие же, как для ArrayAgg.ordering.

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

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

class HotelReservation(model.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.

Устаревшее с версии 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)

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

Примечание

Аргумент 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']}

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

>>> 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}