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

Возвращает 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}