PostgreSQL-specifika aggregeringsfunktioner

Dessa funktioner är tillgängliga från modulen django.contrib.postgres.aggregates. De beskrivs mer detaljerat i PostgreSQL-dokumenten.

Observera

Alla funktioner levereras utan standardaliaser, så du måste uttryckligen ange en. Till exempel:

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

Gemensamma aggregerade optioner

Alla aggregat har nyckelordsargumentet filter och de flesta har också nyckelordsargumentet default.

Aggregeringsfunktioner för allmänt bruk

ArrayAgg

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

Returnerar en lista med värden, inklusive nollvärden, sammanlänkade till en array, eller default om det inte finns några värden.

distinct

Ett valfritt booleskt argument som avgör om matrisvärdena ska vara distinkta. Standardvärdet är False.

order_by

New in Django 5.2.

En valfri sträng med ett fältnamn (med ett valfritt prefix "-" som anger fallande ordning) eller ett uttryck (eller en tupel eller en lista med strängar och/eller uttryck) som anger ordningen på elementen i resultatlistan.

Exempel:

from django.db.models import F

ArrayAgg("a_field", order_by="-some_field")
ArrayAgg("a_field", order_by=F("some_field").desc())

Deprecated since version 5.2: Nyckelordsargumentet ordering är föråldrat. Använd ArrayAgg.order_by istället.

Bit och

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

Returnerar ett int av bitvis AND av alla icke-null värden, eller default om alla värden är null.

BitOr

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

Returnerar ett int av det bitvisa OR av alla icke-null indatavärden, eller default om alla värden är null.

BitXor

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

Returnerar en int av den bitvisa XOR av alla icke-null-ingångsvärden, eller default om alla värden är null. Det kräver PostgreSQL 14+.

BoolAnd

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

Returnerar True, om alla indatavärden är sanna, default om alla värden är null eller om det inte finns några värden, annars False.

Exempel på användning:

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)

Returnerar True om minst ett inmatningsvärde är sant, default om alla värden är null eller om det inte finns några värden, annars False.

Exempel på användning:

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, order_by=(), **extra)

Returnerar indatavärdena som en JSON-array, eller default om det inte finns några värden. Du kan fråga efter resultatet med hjälp av nyckel- och indexuppslagningar.

distinct

Ett valfritt booleskt argument som avgör om matrisvärdena ska vara distinkta. Standardvärdet är False.

order_by

New in Django 5.2.

En valfri sträng med ett fältnamn (med ett valfritt prefix "-" som anger fallande ordning) eller ett uttryck (eller en tupel eller en lista med strängar och/eller uttryck) som anger ordningen på elementen i resultatlistan.

Exemplen är desamma som för ArrayAgg.order_by.

Exempel på användning:

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",
...         order_by="-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}
]}]>

Deprecated since version 5.2: Nyckelordsargumentet ordering är föråldrat. Använd JSONBAgg.order_by istället.

StringAgg

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

Returnerar indatavärdena sammankopplade till en sträng, åtskilda av strängen delimiter eller default om det inte finns några värden.

delimiter

Obligatoriskt argument. Måste vara en sträng.

distinct

Ett valfritt booleanskt argument som avgör om sammanlänkade värden ska vara distinkta. Standardvärdet är False.

order_by

New in Django 5.2.

En valfri sträng med ett fältnamn (med ett valfritt prefix "-" som anger fallande ordning) eller ett uttryck (eller en tupel eller en lista med strängar och/eller uttryck) som anger ordningen på elementen i resultatsträngen.

Exemplen är desamma som för ArrayAgg.order_by.

Exempel på användning:

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=", ",
...         order_by="publications__title",
...     )
... ).values("headline", "publication_names")
<QuerySet [{
    'headline': 'NASA uses Python', 'publication_names': 'Science News, The Python Journal'
}]>

Deprecated since version 5.2: Nyckelordsargumentet ordering är föråldrat. Använd StringAgg.order_by istället.

Aggregerade funktioner för statistik

y och x

Argumenten y och x för alla dessa funktioner kan vara namnet på ett fält eller ett uttryck som returnerar numeriska data. Båda är obligatoriska.

Corr

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

Returnerar korrelationskoefficienten som en flata, eller standard om det inte finns några matchande rader.

CovarPop

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

Returnerar populationens kovarians som en flata, eller standard om det inte finns några matchande rader.

sample

Valfritt. Som standard returnerar CovarPop den allmänna populationens kovarians. Men om sample=True, kommer returvärdet att vara urvalspopulationens kovarians.

RegrAvgX

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

Returnerar medelvärdet av den oberoende variabeln (sum(x)/N) som en flata, eller standard om det inte finns några matchande rader.

RegrAvgY

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

Returnerar medelvärdet av den beroende variabeln (sum(y)/N) som en flata, eller standard om det inte finns några matchande rader.

RegrCount

class RegrCount(y, x, filter=None)

Returnerar ett int av antalet indatarader där båda uttrycken inte är null.

Observera

Argumentet default stöds inte.

RegrIntercept

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

Returnerar y-interceptet för den linjära ekvationen med minsta kvadratanpassning som bestäms av paren (x, y) som en float, eller default om det inte finns några matchande rader.

RegrR2

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

Returnerar kvadraten på korrelationskoefficienten som en float, eller default om det inte finns några matchande rader.

RegrSlope

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

Returnerar lutningen för den linjära ekvationen med minsta kvadratanpassning som bestäms av paren (x, y) som en flata, eller default om det inte finns några matchande rader.

RegrSXX

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

Returnerar sum(x^2) - sum(x)^2/N (”kvadratsumman” för den oberoende variabeln) som en float, eller default om det inte finns några matchande rader.

RegrSXY

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

Returnerar sum(x*y) - sum(x) * sum(y)/N (”summan av produkter” av oberoende gånger beroende variabel) som en float, eller default om det inte finns några matchande rader.

RegrSYY

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

Returnerar sum(y^2) - sum(y)^2/N (”kvadratsumman” för den beroende variabeln) som en float, eller default om det inte finns några matchande rader.

Exempel på användning

Vi kommer att använda denna exempeltabell:

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

Här följer några exempel på några av de allmänna aggregeringsfunktionerna:

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

Nästa exempel visar användningen av statistiska aggregatfunktioner. Den underliggande matematiken kommer inte att beskrivas (du kan läsa om detta, till exempel på 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}