# Documentation Django 3.1.9.dev

# 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.

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

Options communes d’agrégation

Tous les agrégats disposent du paramètre nommé filter.

## Fonctions d’agrégation d’ordre général

### `ArrayAgg`

class `ArrayAgg`(expression, distinct=False, filter=None, ordering=(), **extra)

  Renvoie une liste de valeurs, y compris nulles, concaténées dans un tableau.

  `distinct`

    Un paramètre booléen facultatif qui détermine si les valeurs de tableau seront distinctes. `False` par défaut.

  `ordering`

    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 :

        'some_field'
        '-some_field'
        from django.db.models import F
        F('some_field').desc()

### `BitAnd`

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

  Renvoie un entier `int` résultat de l’opération `AND` bit-à-bit de toutes les valeurs non nulles, ou `None` si toutes les valeurs sont nulles.

### `BitOr`

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

  Renvoie un entier `int` résultat de l’opération `OR` bit-à-bit de toutes les valeurs non nulles, ou `None` si toutes les valeurs sont nulles.

### `BoolAnd`

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

  Renvoie `True` si toutes les valeurs d’entrée sont vraies, `None` 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 BooleanField, 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), output_field=BooleanField()))
      {'booland': True}

### `BoolOr`

class `BoolOr`(expression, filter=None, **extra)

  Renvoie `True` si au moins une valeur d’entrée est vraie, `None` 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 BooleanField, 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), output_field=BooleanField()))
      {'boolor': False}

### `JSONBAgg`

class `JSONBAgg`(expressions, filter=None, **extra)

  Renvoie les valeurs d’entrée sous forme de tableau `JSON`.

### `StringAgg`

class `StringAgg`(expression, delimiter, distinct=False, filter=None, ordering=())

  Renvoie les valeurs d’entrée concaténées dans une chaîne, séparées par la chaîne `delimiter`.

  `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.

  `ordering`

    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.ordering`.

## 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)

  Renvoie le coefficient de corrélation sous forme de nombre `float`, ou `None` si aucune ligne ne correspond.

### `CovarPop`

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

  Renvoie la covariance de population sous forme de nombre `float`, ou `None` si aucune ligne ne correspond.

  Accepte un paramètre facultatif :

  `sample`

    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)

  Renvoie la moyenne de la variable indépendante (`sum(x)/N`) sous forme de nombre `float`, ou `None` si aucune ligne ne correspond.

### `RegrAvgY`

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

  Renvoie la moyenne de la variable dépendante (`sum(y)/N`) sous forme de nombre `float`, ou `None` 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.

### `RegrIntercept`

class `RegrIntercept`(y, x, filter=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 `None` si aucune ligne ne correspond.

### `RegrR2`

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

  Returns the square of the correlation coefficient as a `float`, or `None` if there aren’t any matching rows.

### `RegrSlope`

class `RegrSlope`(y, x, filter=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 `None` si aucune ligne ne correspond.

### `RegrSXX`

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

  Renvoie `sum(x^2) - sum(x)^2/N` (« somme des carrés » de la variable indépendante) sous forme de nombre `float`, ou `None` si aucune ligne ne correspond.

### `RegrSXY`

class `RegrSXY`(y, x, filter=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 `None` si aucune ligne ne correspond.

### `RegrSYY`

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

  Renvoie `sum(y^2) - sum(y)^2/N` (« somme des carrés » de la variable dépendante) sous forme de nombre `float`, ou `None` si aucune ligne ne correspond.

## Exemples d’utilisation

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}