Ces fonctions sont disponibles dans le module django.contrib.postgres.aggregates
. Elles sont décrites plus en détails dans la documentation PostgreSQL.
Note
Toutes ces fonctions n’ont pas d’alias par défaut, il faut donc en indiquer un explicitement. Par exemple :
>>> SomeModel.objects.aggregate(arr=ArrayAgg("somefield"))
{'arr': [0, 1, 2]}
ArrayAgg
¶Renvoie une liste de valeurs, y compris nulles, concaténées dans un tableau, ou default
s’il n’y a aucune valeur.
Un paramètre booléen facultatif qui détermine si les valeurs de tableau seront distinctes. False
par défaut.
Une chaîne facultative d’un nom de champ (précédé d’un préfixe "-"
facultatif pour indiquer un ordre décroissant) ou une expression (ou un tuple/liste de chaînes ou d’expressions) qui indique le tri des éléments de la liste résultante.
Exemples :
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: The ordering
keyword argument is deprecated. Use
ArrayAgg.order_by
instead.
BitAnd
¶Renvoie un entier int
résultat de l’opération AND
bit-à-bit de toutes les valeurs non nulles, ou default
si toutes les valeurs sont nulles.
BitOr
¶Renvoie un entier int
résultat de l’opération OR
bit-à-bit de toutes les valeurs non nulles, ou default
si toutes les valeurs sont nulles.
BitXor
¶Renvoie un entier int
résultat de l’opération XOR
bit-à-bit de toutes les valeurs non nulles, ou default
si toutes les valeurs sont nulles. Nécessite PostgreSQL 14+.
BoolAnd
¶Renvoie True
si toutes les valeurs d’entrée sont vraies, default
si toutes les valeurs sont nulles ou s’il n’y a pas de valeur, sinon renvoie False
.
Exemple d’utilisation :
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
¶Renvoie True
si au moins une valeur d’entrée est vraie, default
si toutes les valeurs sont nulles ou s’il n’y a pas de valeur, sinon renvoie False
.
Exemple d’utilisation :
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
¶Renvoie les valeurs d’entrée sous forme de tableau JSON
, ou default
s’il n’y a aucune valeur. Vous pouvez interroger le résultat en utilisant les expressions de clé et d'indice
.
Un paramètre booléen facultatif qui détermine si les valeurs de tableau seront distinctes. False
par défaut.
Une chaîne facultative d’un nom de champ (précédé d’un préfixe "-"
facultatif pour indiquer un ordre décroissant) ou une expression (ou un tuple/liste de chaînes ou d’expressions) qui indique le tri des éléments de la liste résultante.
Examples are the same as for ArrayAgg.order_by
.
Exemple d’utilisation :
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: The ordering
keyword argument is deprecated. Use
JSONBAgg.order_by
instead.
StringAgg
¶Renvoie les valeurs d’entrée concaténées dans une chaîne, séparées par la chaîne delimiter
, ou default
s’il n’y a aucune valeur.
Paramètre obligatoire. Doit être une chaîne.
Un paramètre booléen facultatif qui détermine si les valeurs concaténées seront distinctes. False
par défaut.
Une chaîne facultative d’un nom de champ (précédé d’un préfixe "-"
facultatif pour indiquer un ordre décroissant) ou une expression (ou un tuple/liste de chaînes ou d’expressions) qui indique le tri des éléments de la chaîne résultante.
Examples are the same as for ArrayAgg.order_by
.
Exemple d’utilisation :
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: The ordering
keyword argument is deprecated. Use
StringAgg.order_by
instead.
y
et x
¶Les paramètres y
et x
de toutes ces fonctions peuvent être un nom de champ ou une expression renvoyant une donnée numérique. Les deux sont obligatoires.
Corr
¶Renvoie le coefficient de corrélation sous forme de nombre float
, ou default
si aucune ligne ne correspond.
CovarPop
¶Renvoie la covariance de population sous forme de nombre float
, ou default
si aucune ligne ne correspond.
Facultatif. Par défaut, CovarPop
renvoie la covariance de population générale. Cependant, si sample=True
, la valeur renvoyée sera la covariance d’échantillon de population.
RegrAvgX
¶Renvoie la moyenne de la variable indépendante (sum(x)/N
) sous forme de nombre float
, ou default
si aucune ligne ne correspond.
RegrAvgY
¶Renvoie la moyenne de la variable dépendante (sum(y)/N
) sous forme de nombre float
, ou default
si aucune ligne ne correspond.
RegrCount
¶Renvoie un entier int
correspondant au nombre de lignes d’entrée dans lesquelles les deux expressions ne sont pas nulles.
Note
Le paramètre default
n’est pas pris en charge.
RegrIntercept
¶Renvoie l’interception de l’axe y pour l’équation linéaire de la méthode des moindres carrés déterminée par les paires (x, y)
sous forme de nombre float
, ou default
si aucune ligne ne correspond.
RegrR2
¶Returns the square of the correlation coefficient as a float
, or
default
if there aren’t any matching rows.
RegrSlope
¶Renvoie l’inclinaison pour l’équation linéaire de la méthode des moindres carrés déterminée par les paires (x, y)
sous forme de nombre float
, ou default
si aucune ligne ne correspond.
RegrSXX
¶Renvoie sum(x^2) - sum(x)^2/N
(« somme des carrés » de la variable indépendante) sous forme de nombre float
, ou default
si aucune ligne ne correspond.
RegrSXY
¶Renvoie sum(x*y) - sum(x) * sum(y)/N
(« somme des produits » de la variable indépendante multipliée par la variable dépendante) sous forme de nombre float
, ou default
si aucune ligne ne correspond.
RegrSYY
¶Renvoie sum(y^2) - sum(y)^2/N
(« somme des carrés » de la variable dépendante) sous forme de nombre float
, ou default
si aucune ligne ne correspond.
Nous allons utiliser cette table d’exemple :
| FIELD1 | FIELD2 | FIELD3 |
|--------|--------|--------|
| foo | 1 | 13 |
| bar | 2 | (null) |
| test | 3 | 13 |
Voici quelques exemples de certaines des fonctions d’agrégation d’ordre général :
>>> 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']}
L’exemple suivant montre l’utilisation des fonctions d’agrégats pour les statistiques. Les mathématiques sous-jacentes ne sont pas expliquées (vous pouvez vous renseigner à ce sujet sur Wikipédia par exemple) :
>>> 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}
avr. 05, 2025