--- title: "Fonctions d’agrégation spécifiques à PostgreSQL" version: 5.2 locale: fr source: https://docs.djangoproject.com/fr/5.2/ref/contrib/postgres/aggregates/ canonical: https://djangodocs.dev/fr/5.2/ref/contrib/postgres/aggregates/ --- # Fonctions d’agrégation spécifiques à PostgreSQL Ces fonctions sont disponibles dans le module `django.contrib.postgres.aggregates`. Elles sont décrites plus en détails dans la [documentation PostgreSQL](https://www.postgresql.org/docs/current/functions-aggregate.html). > **Note** > > Toutes ces fonctions n’ont pas d’alias par défaut, il faut donc en indiquer un explicitement. Par exemple : > > ```pycon > >>> SomeModel.objects.aggregate(arr=ArrayAgg("somefield")) > {'arr': [0, 1, 2]} > ``` > **Options communes d’agrégation** > > Tous les agrégats possèdent le paramètre mot-clé [filter](/fr/5.2/ref/models/querysets/#aggregate-filter) et doivent aussi avoir le paramètre mot-clé [default](/fr/5.2/ref/models/querysets/#aggregate-default). ## Fonctions d’agrégation d’ordre général ### `ArrayAgg` #### `class ArrayAgg(expression, distinct=False, filter=None, default=None, order_by=(), **extra)` Renvoie une liste de valeurs, y compris nulles, concaténées dans un tableau, ou `default` s’il n’y a aucune valeur. #### `distinct` Un paramètre booléen facultatif qui détermine si les valeurs de tableau seront distinctes. `False` par défaut. #### `order_by` > **New in Django 5.2** 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 Django 5.2** > > Obsolète depuis la version 5.2: L’argument nommé `ordering` est obsolète. Utilisez [`ArrayAgg.order_by`](#django.contrib.postgres.aggregates.ArrayAgg.order_by) à la place. ### `BitAnd` #### `class BitAnd(expression, filter=None, default=None, **extra)` 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` #### `class BitOr(expression, filter=None, default=None, **extra)` 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` #### `class BitXor(expression, filter=None, default=None, **extra)` 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` #### `class BoolAnd(expression, filter=None, default=None, **extra)` 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() ``` ```pycon >>> 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)` 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() ``` ```pycon >>> 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)` 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`](/fr/5.2/topics/db/queries/#std-fieldlookup-jsonfield.key). #### `distinct` Un paramètre booléen facultatif qui détermine si les valeurs de tableau seront distinctes. `False` par défaut. #### `order_by` > **New in Django 5.2** 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. Les exemples sont les mêmes que pour [`ArrayAgg.order_by`](#django.contrib.postgres.aggregates.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) ``` ```pycon >>> 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") ``` > **Deprecated since Django 5.2** > > Obsolète depuis la version 5.2: L’argument nommé `ordering` est obsolète. Utilisez [`JSONBAgg.order_by`](#django.contrib.postgres.aggregates.JSONBAgg.order_by) à la place. ### `StringAgg` #### `class StringAgg(expression, delimiter, distinct=False, filter=None, default=None, order_by=())` 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. #### `delimiter` Paramètre obligatoire. Doit être une chaîne. #### `distinct` Un paramètre booléen facultatif qui détermine si les valeurs concaténées seront distinctes. `False` par défaut. #### `order_by` > **New in Django 5.2** 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. Les exemples sont les mêmes que pour [`ArrayAgg.order_by`](#django.contrib.postgres.aggregates.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) ``` ```pycon >>> article = Article.objects.create(headline="NASA uses Python") >>> article.publications.create(title="The Python Journal") >>> article.publications.create(title="Science News") >>> from django.contrib.postgres.aggregates import StringAgg >>> Article.objects.annotate( ... publication_names=StringAgg( ... "publications__title", ... delimiter=", ", ... order_by="publications__title", ... ) ... ).values("headline", "publication_names") ``` > **Deprecated since Django 5.2** > > Obsolète depuis la version 5.2: L’argument nommé `ordering` est obsolète. Utilisez [`StringAgg.order_by`](#django.contrib.postgres.aggregates.StringAgg.order_by) à la place. ## Fonctions d’agrégation à but statistique ### `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` #### `class Corr(y, x, filter=None, default=None)` Renvoie le coefficient de corrélation sous forme de nombre `float`, ou `default` si aucune ligne ne correspond. ### `CovarPop` #### `class CovarPop(y, x, sample=False, filter=None, default=None)` Renvoie la covariance de population sous forme de nombre `float`, ou `default` si aucune ligne ne correspond. #### `sample` 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` #### `class RegrAvgX(y, x, filter=None, default=None)` Renvoie la moyenne de la variable indépendante (`sum(x)/N`) sous forme de nombre `float`, ou `default` si aucune ligne ne correspond. ### `RegrAvgY` #### `class RegrAvgY(y, x, filter=None, default=None)` Renvoie la moyenne de la variable dépendante (`sum(y)/N`) sous forme de nombre `float`, ou `default` si aucune ligne ne correspond. ### `RegrCount` #### `class RegrCount(y, x, filter=None)` 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` #### `class RegrIntercept(y, x, filter=None, default=None)` 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` #### `class RegrR2(y, x, filter=None, default=None)` Returns the square of the correlation coefficient as a `float`, or `default` if there aren’t any matching rows. ### `RegrSlope` #### `class RegrSlope(y, x, filter=None, default=None)` 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` #### `class RegrSXX(y, x, filter=None, default=None)` 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` #### `class RegrSXY(y, x, filter=None, default=None)` 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` #### `class RegrSYY(y, x, filter=None, default=None)` 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. ## Exemples d’utilisation Nous allons utiliser cette table d’exemple : ```text | 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 : ```pycon >>> 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](https://fr.wikipedia.org/wiki/Régression_(statistiques)) par exemple) : ```pycon >>> 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} ```