xaggr.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

 <sect1 id="xaggr">
  <title>Agrégats utilisateur</title>

  <indexterm zone="xaggr">
   <primary>fonctions agrégat</primary>
   <secondary>extension</secondary>
  </indexterm>

  <para>
   Dans <productname>PostgreSQL</productname>, les fonctions d'agrégat  
   sont exprimées comme des <firstterm>valeurs d'état</firstterm>
   et des <firstterm>fonctions de transition d'état</firstterm>.
   C'est-à-dire qu'un agrégat opère en utilisant une valeur d'état qui est mis
   à jour à chaque ligne traitée.
   Pour définir une nouvelle fonction d'agrégat, on choisit
   un type de donnée pour la valeur d'état, une valeur initiale pour l'état et
   une fonction de transition d'état. La fonction de transition d'état est
   une fonction ordinaire qui peut être utilisée hors agrégat.
   Une <firstterm>fonction finale</firstterm> peut
   également être spécifiée pour le cas où le résultat désiré comme agrégat est
   différent des données conservées comme valeur d'état courant.
  </para>

  <para>
   Ainsi, en plus des types de données d'argument et de résultat vus par
   l'utilisateur, il existe un type de données pour la valeur d'état interne qui
   peut être différent des deux autres.</para>

  <para>
   Un agrégat qui n'utilise pas de fonction finale est un agrégat qui utilise
   pour chaque ligne une fonction dépendante des valeurs de colonnes.
   <function>sum</function> en est un exemple.
   <function>sum</function> débute à zéro et ajoute la valeur de la ligne
   courante à son total en cours. Par exemple, pour obtenir un agrégat
   <function>sum</function> qui opère sur un type de données nombres
   complexes, il suffira décrire la fonction d'addition pour ce type de donnée.
   La définition de l'agrégat sera&nbsp;:
<screen>CREATE AGGREGATE somme (complex)
(
    sfunc = ajout_complexe,
    stype = complexe,
    initcond = '(0,0)'
);

SELECT somme(a) FROM test_complexe;

   somme
-----------
 (34,53.9)
</screen>

   (Notez que nous nous reposons sur une surcharge de fonction&nbsp;: il existe
   plus d'un agrégat nommé <function>sum</function> mais
   <productname>PostgreSQL</productname> trouve le type de somme s'appliquant à
   une colonne de type <type>complex</type>.)
 </para> 
  <para>
   La définition précédente de <function>sum</function> retournera zéro (la
   condition d'état initial) s'il n'y a que des valeurs d'entrée NULL.
   Dans ce cas, on peut souhaiter qu' elle retourne NULL &mdash; le
   standard SQL prévoit que la fonction <function>sum</function> se comporte
   ainsi. Cela peut être obtenu par l'omission de l'instruction
   <literal>initcond</literal>, de sorte que la condition d'état initial soit
   NULL.
   Dans ce cas, <literal>sfunc</literal> vérifie l'entrée d'une condition
   d'état NULL mais, pour <function>sum</function> et quelques
   autres agrégats simples comme <function>max</function> et <function>min</function>, il
   suffit d'insérer la première valeur d'entrée non NULL dans la variable d'état
   et d'appliquer la fonction de transition d'état à partir de la
   seconde valeur non NULL. 
   <productname>PostgreSQL</productname> fait cela automatiquement si la
   condition initiale est NULL et si la fonction de transition est marquée
   <quote>strict</quote> (elle n'est pas appelée pour les entrées NULL).
  </para> 
   <para>
    Par défaut également, pour les fonctions de transition <quote>strict</quote>, 
    la valeur d'état précédente reste inchangée pour une entrée NULL. 
    Les valeurs NULL sont ainsi ignorées. 
    Pour obtenir un autre comportement, il suffit de ne
    pas déclarer la fonction de transition <quote>strict</quote>. À la place,
    codez-la de façon à ce qu'elle vérifie et traite les entrées NULL.
 </para>
  
  <para>
   <function>avg</function> (average = moyenne) est un exemple plus complexe d'agrégat.
   Il demande deux états courants&nbsp;: la somme des entrées et le
   nombre d'entrées. Le résultat final est obtenu en divisant ces quantités. La
   moyenne est typiquement implantée en utilisant comme valeur d'état un
   tableau de deux éléments. Par exemple, l'implémentation intégrée de
   <function>avg(float8)</function> ressemble à&nbsp;:

<programlisting>CREATE AGGREGATE avg (float8)
(
    sfunc = float8_accum,
    stype = float8[],
    finalfunc = float8_avg,
    initcond = '{0,0}'
);
</programlisting>
  </para>

  <para>
   Les fonctions d'agrégat peuvent utiliser des fonctions d'état transitionnelles
   ou des fonctions finales polymorphes. De cette façon, les mêmes fonctions
   peuvent être utilisées pour de multiples agrégats. Voir la <xref
   linkend="extend-types-polymorphic"/> pour une explication des fonctions polymorphes.
   La fonction d'agrégat elle-même peut être
   spécifiée avec un type de base et des types d'état polymorphes, ce qui permet
   ainsi à une unique définition de fonction de servir pour de multiples types
   de données en entrée. Voici un exemple d'agrégat polymorphe&nbsp;:

<programlisting>CREATE AGGREGATE array_accum (anyelement)
(
    sfunc = array_append,
    stype = anyarray,
    initcond = '{}'
);
</programlisting>

   Dans ce cas, le type d'état effectif pour tout appel d'agrégat est le type
   tableau avec comme éléments le type effectif d'entrée. Le comportement de
   l'agrégat est de concaténer toutes les entrées dans un tableau de ce type.
   (Note&nbsp;: l'agrégat <function>array_agg</function> fournit une
   fonctionnalité similaire, avec de meilleures performances que ne pourrait
   avoir cette définition.)
</para>

  <para>
   Voici le résultat pour deux types de données différents en arguments&nbsp;:
<programlisting>SELECT attrelid::regclass, array_accum(attname)
FROM pg_attribute WHERE attnum &gt; 0
AND attrelid = 'pg_tablespace'::regclass GROUP BY attrelid;
   attrelid    |              array_accum              
---------------+---------------------------------------
 pg_tablespace | {spcname,spcowner,spclocation,spcacl}
(1 row)

SELECT attrelid::regclass, array_accum(atttypid::regtype)
    FROM pg_attribute
    WHERE attnum &gt; 0 AND attrelid = 'pg_tablespace'::regclass
    GROUP BY attrelid;

   attrelid    |        array_accum        
---------------+---------------------------
 pg_tablespace | {name,oid,text,aclitem[]}
(1 row)
</programlisting>
  </para>

  <!-- J'ai besoin de la VO, vraiment !!! -->
  <para>
   En fonction du <quote>contexte</quote> de l'appel, consultable
   par le n&oelig;ud <structname>AggState</structname> ou
   <structname>WindowAggState</structname>, une fonction C 
   sait si elle est appelée en tant que
   transition d'agrégat ou en tant que fonction finale. Par exemple&nbsp;:
<programlisting>        if (fcinfo-&gt;context &amp;&amp;
            (IsA(fcinfo-&gt;context, AggState) ||
             IsA(fcinfo-&gt;context, WindowAggState)))
</programlisting>
   L'intérêt de cette vérification est que, lorsque cela est vrai pour une
   fonction de transition, la première
   entrée doit être une valeur de transition, temporaire, et peut donc être
   modifiée sans risque plutôt que d'allouer une nouvelle copie (ceci est
   <emphasis>seulement</emphasis> le cas quand la modification d'une entrée passée par
   référence est sûre pour une fonction. En particulier, les fonctions finales
   d'agrégat ne devraient pas modifier leurs entrées dans tous les cas car
   elles seront ré-exécutées dans certains cas sur la même valeur de transition
   finale). Voir <literal>int8inc()</literal> pour un
   exemple.
  </para>
<!-- Rien compris -->
  <para>
   Pour de plus amples détails, on se réfèrera à la commande
   <xref linkend="sql-createaggregate" endterm="sql-createaggregate-title"/>.
  </para>
 </sect1>