CREATE AGGREGATE

Nom

CREATE AGGREGATE -- définit une nouvelle fonction d'agrégat

Synopsis

CREATE AGGREGATE nom (
    BASETYPE = type_donnée_entrée,
    SFUNC = sfonc,
    STYPE = type_donnée_état
    [ , FINALFUNC = ffonc ]
    [ , INITCOND = condition_initiale ]
)

Description

CREATE AGGREGATE définit une nouvelle fonction d'agrégat. Certaines fonctions d'agrégat pour les types de base comme min(integer) et avg(double precision) sont déjà fournies dans la distribution standard. Si une d'entre elles définit de nouveaux types ou a besoin d'une fonction d'agrégat non fournie, alors CREATE AGGREGATE peut être utilisé pour fournir les fonctionnalités désirées.

Si un nom de schéma est donné (par exemple, CREATE AGGREGATE monschema.monagg ...), alors la fonction d'agrégat est créée dans le schéma spécifié. Sinon, elle est créée dans le schéma courant.

Une fonction d'agrégat est identifiée par son nom et son type de données en entrée. Deux agrégats dans le même schéma peuvent avoir le même nom s'ils opèrent sur des types différents en entrée. Le nom et le type de données en entrée d'un agrégat doivent aussi être distincts du nom et du type de données de toutes les fonctions ordinaires du même schéma.

Une fonction d'agrégat est réalisée à partir d'une ou deux fonctions ordinaires : une fonction de transition d'état sfonc, et une fonction de traitement final optionnelle ffonc. Elles sont utilisées ainsi :

sfonc( état-interne, nouvel-élément-données ) ---> prochain-état-interne
ffonc( état-interne ) ---> valeur-agrégat

PostgreSQL crée une variable temporaire de type stype pour contenir l'état interne courant de l'agrégat. À chaque élément de données en entrée, la fonction de transition d'état est appelée pour calculer une nouvelle valeur de l'état interne. Une fois que toutes les données sont traitées, la fonction finale est appelée une fois pour calculer la valeur de retour de l'agrégat. S'il n'existe pas de fonction finale, alors la valeur d'état final est retournée ainsi.

Une fonction d'agrégat peut fournir une condition initiale, c'est-à-dire une valeur initiale pour la valeur de l'état interne. Ceci est spécifié et stocké dans la base de données comme une colonne de type text mais doit être une représentation externe valide d'une constante du type de donnée de la valeur de l'état. Si elle n'est pas fournie, la valeur de l'état commence avec NULL.

Si la fonction de transition de l'état est déclarée << strict >>, alors elle ne peut pas être appelée avec des entrées NULL. Avec une telle fonction de transition, l'exécution d'agrégat se comporte ainsi. Les valeurs des entrées NULL sont ignorées (la fonction n'est pas appelée et la valeur de l'état précédent est conservée). Si la valeur de l'état initial est NULL, alors la première valeur en entrée non NULL remplace la valeur de l'état et la fonction de transition est appelée en commençant avec la seconde valeur en entrée non NULL. Ceci est pratique pour implémenter les agrégats comme max. Notez que ce comportement est seulement disponible quand type_donnée_état est identique à type_donnée_entrée. Lorsque ces types sont différents, vous devez fournir une condition initiale non NULL ou utiliser une fonction de transition non stricte.

Si la fonction de transition d'état n'est pas stricte, alors elle sera appelée sans condition à chaque valeur en entrée et devra gérer les entrées NULL et les valeurs de transition NULL. Ceci permet à l'auteur de l'agrégat d'avoir le contrôle complet sur la gestion des valeurs NULL par l'agrégat.

Si la fonction finale est déclarée << strict >>, alors elle ne sera pas appelée quand la valeur d'état finale est NULL ; à la place, un résultat NULL sera retourné automatiquement. (Bien sûr, c'est simplement le comportement normal de fonctions strictes.) Dans tous les cas, la fonction finale a l'option de renvoyer une valeur NULL. Par exemple, la fonction finale pour avg renvoie NULL lorsqu'elle n'a aucune lignes en entrée.

Paramètres

nom

Le nom de la fonction d'agrégat à créer (pouvant être qualifié avec le nom du schéma).

type_donnée_entrée

Le type de données en entrée sur lequel opère la fonction d'agrégat. Elle peut être spécifiée comme "ANY" pour un agrégat qui n'examine pas les valeurs en entrée (un exemple est count(*)).

sfonc

Le nom de la fonction de transition de l'état à appeler pour chaque valeur en entrée. C'est normalement une fonction à deux arguments, le premier étant de type type_donnée_état et le second de type type_donnée_entrée. Autrement, pour un agrégat qui n'examine pas les valeurs en entrée, la fonction prend un seul argument de type type_donnée_état. Dans chaque cas, la fonction doit renvoyer une valeur de type type_donnée_état. Cette fonction prend la valeur de l'état en cours et l'élément de donnée en cours et renvoie la prochaine valeur d'état.

type_donnée_état

Le type de donnée pour la valeur d'état de l'agrégat.

ffonc

Le nom de la fonction finale à appeler pour traiter le résultat de l'agrégat une fois que toutes les données en entrée aient été parcourues. La fonction prend un seul argument de type type_donnée_état. Le type de retour de l'agrégat de la fonction est défini comme le type de retour de cette fonction. Si ffonc n'est pas spécifiée, alors la valeur d'état finale est utilisée comme résultat de l'agrégat et le type de retour est type_donnée_état.

condition_initiale

La configuration initiale pour la valeur de l'état. Elle doit être une constante de type chaîne de caractères dans la forme acceptée par le type de données type_donnée_état. Si non spécifié, la valeur d'état commence à NULL.

Les paramètres de CREATE AGGREGATE peuvent être écrit dans n'importe quel ordre, pas uniquement dans l'ordre illustré ci-dessus.

Exemples

Voir Section 33.9.

Compatibilité

CREATE AGGREGATE est une extension du langage PostgreSQL. Le standard SQL ne fournit pas de fonctions d'agrégat définies par l'utilisateur.

Voir aussi

ALTER AGGREGATE, DROP AGGREGATE