root/traduc/branches/bv747/manuel/ref/create_aggregate.sgml

<!--
$Header: /var/lib/cvs/pgsql-fr/sgml/ref/create_aggregate.sgml,v 1.7.2.2 2005/04/02 06:45:58 guillaume Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATEAGGREGATE">
 <refmeta>
  <refentrytitle id="sql-createaggregate-title">CREATE AGGREGATE</refentrytitle>
  <refmiscinfo>SQL - Instructions du langage</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE AGGREGATE</refname>
  <refpurpose>définit une nouvelle fonction d'agrégat</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createaggregate">
  <primary>CREATE AGGREGATE</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE AGGREGATE <replaceable class="PARAMETER">nom</replaceable> (
    BASETYPE = <replaceable class="PARAMETER">type_donnée_entrée</replaceable>,
    SFUNC = <replaceable class="PARAMETER">sfonc</replaceable>,
    STYPE = <replaceable class="PARAMETER">type_donnée_état</replaceable>
    [ , FINALFUNC = <replaceable class="PARAMETER">ffonc</replaceable> ]
    [ , INITCOND = <replaceable
class="PARAMETER">condition_initiale</replaceable> ]
)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE AGGREGATE</command> définit une nouvelle fonction d'agrégat.
   Certaines fonctions d'agrégat pour les types de base comme
   <function>min(integer)</function> et <function>avg(double
   precision)</function> 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 <command>CREATE AGGREGATE</command> peut être
   utilisé pour fournir les fonctionnalités désirées.
  </para>

  <para>
   Si un nom de schéma est donné (par exemple, <literal>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.
  </para>

  <para>
   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.
  </para>

  <para>
   Une fonction d'agrégat est réalisée à partir d'une ou deux fonctions
   ordinaires&nbsp;:
   une fonction de transition d'état
   <replaceable class="PARAMETER">sfonc</replaceable>,
   et une fonction de traitement final optionnelle
   <replaceable class="PARAMETER">ffonc</replaceable>.
   Elles sont utilisées ainsi&nbsp;:
<programlisting>
<replaceable class="PARAMETER">sfonc</replaceable>( état-interne, nouvel-élément-données ) ---> prochain-état-interne
<replaceable class="PARAMETER">ffonc</replaceable>( état-interne ) ---> valeur-agrégat
</programlisting>
  </para>

  <para>
   <productname>PostgreSQL</productname> crée une variable temporaire de type
   <replaceable class="PARAMETER">stype</replaceable> 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.
  </para>
  
  <para>
   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 <type>text</type> 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.
  </para>
  
  <para>
   Si la fonction de transition de l'état est déclarée <quote>strict</quote>,
   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
   <function>max</function>. Notez que ce comportement est seulement disponible
   quand <replaceable class="PARAMETER">type_donnée_état</replaceable> est
   identique à <replaceable class="PARAMETER">type_donnée_entrée</replaceable>.
   Lorsque ces types sont différents, vous devez fournir une condition initiale
   non NULL ou utiliser une fonction de transition non stricte.
  </para>
  
  <para>
   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.
  </para>
  
  <para>
   Si la fonction finale est déclarée <quote>strict</quote>, alors elle ne sera
   pas appelée quand la valeur d'état finale est NULL&nbsp;; à 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 <function>avg</function> renvoie NULL lorsqu'elle n'a aucune
   lignes en entrée.
  </para>
 </refsect1>

 <refsect1>
  <title>Paramètres</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="PARAMETER">nom</replaceable></term>
    <listitem>
     <para>
      Le nom de la fonction d'agrégat à créer (pouvant être qualifié avec le nom
      du schéma).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">type_donnée_entrée</replaceable></term>
    <listitem>
     <para>
      Le type de données en entrée sur lequel opère la fonction d'agrégat. Elle
      peut être spécifiée comme <literal>"ANY"</> pour un agrégat qui n'examine
      pas les valeurs en entrée (un exemple est <function>count(*)</function>).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">sfonc</replaceable></term>
    <listitem>
     <para>
      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 <replaceable
      class="PARAMETER">type_donnée_état</replaceable> et le second de type
      <replaceable class="PARAMETER">type_donnée_entrée</replaceable>.
      Autrement, pour un agrégat qui n'examine pas les valeurs en entrée, la
      fonction prend un seul argument de type <replaceable
      class="PARAMETER">type_donnée_état</replaceable>. Dans chaque cas, la
      fonction doit renvoyer une valeur de type <replaceable
      class="PARAMETER">type_donnée_état</replaceable>. 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.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">type_donnée_état</replaceable></term>
    <listitem>
     <para>
      Le type de donnée pour la valeur d'état de l'agrégat.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">ffonc</replaceable></term>
    <listitem>
     <para>
      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 <replaceable
      class="PARAMETER">type_donnée_état</replaceable>. Le type de retour de
      l'agrégat de la fonction est défini comme le type de retour de cette
      fonction. Si <replaceable class="PARAMETER">ffonc</replaceable> 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 <replaceable
      class="PARAMETER">type_donnée_état</replaceable>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="PARAMETER">condition_initiale</replaceable></term>
    <listitem>
     <para>
      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 <replaceable class="PARAMETER">type_donnée_état</replaceable>.
      Si non spécifié, la valeur d'état commence à NULL.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   Les paramètres de <command>CREATE AGGREGATE</command> peuvent être écrit
   dans n'importe quel ordre, pas uniquement dans l'ordre illustré ci-dessus.
  </para>
 </refsect1>
  
 <refsect1>
  <title>Exemples</title>

  <para>
   Voir <xref linkend="xaggr">.
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibilité</title>

  <para>
   <command>CREATE AGGREGATE</command> est une extension du langage
   <productname>PostgreSQL</productname>. Le standard SQL ne fournit pas de
   fonctions d'agrégat définies par l'utilisateur.
  </para>
 </refsect1>

 <refsect1>
  <title>Voir aussi</title>

  <simplelist type="inline">
   <member><xref linkend="sql-alteraggregate" endterm="sql-alteraggregate-title"></member>
   <member><xref linkend="sql-dropaggregate" endterm="sql-dropaggregate-title"></member>
  </simplelist>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->