granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_aggregate.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.31 2005/01/04 00:39:53 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEAGGREGATE">
   7  <refmeta>
   8   <refentrytitle id="sql-createaggregate-title">CREATE AGGREGATE</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE AGGREGATE</refname>
  14   <refpurpose>define a new aggregate function</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createaggregate">
  18   <primary>CREATE AGGREGATE</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
  24     BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
  25     SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
  26     STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
  27     [ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
  28     [ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
  29 )
  30 </synopsis>
  31  </refsynopsisdiv>
  32
  33  <refsect1>
  34   <title>Description</title>
  35
  36   <para>
  37    <command>CREATE AGGREGATE</command> defines a new aggregate
  38    function. Some basic and commonly-used aggregate functions are
  39    included with the distribution; they are documented in <xref
  40    linkend="functions-aggregate">. If one defines new types or needs
  41    an aggregate function not already provided, then <command>CREATE
  42    AGGREGATE</command> can be used to provide the desired features.
  43   </para>
  44
  45   <para>
  46    If a schema name is given (for example, <literal>CREATE AGGREGATE
  47    myschema.myagg ...</>) then the aggregate function is created in the
  48    specified schema.  Otherwise it is created in the current schema.
  49   </para>
  50
  51   <para>
  52    An  aggregate  function is identified by its name and input data type.
  53    Two aggregates in the same schema can have the same name if they operate on
  54    different input types.  The
  55    name and input data type of an aggregate must also be distinct from
  56    the name and input data type(s) of every ordinary function in the same
  57    schema.
  58   </para>
  59
  60   <para>
  61    An  aggregate function is made from one or two ordinary
  62    functions:
  63    a state transition function
  64    <replaceable class="PARAMETER">sfunc</replaceable>,
  65    and an optional final calculation function
  66    <replaceable class="PARAMETER">ffunc</replaceable>.
  67    These are used as follows:
  68 <programlisting>
  69 <replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
  70 <replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
  71 </programlisting>
  72   </para>
  73
  74   <para>
  75    <productname>PostgreSQL</productname> creates a temporary variable
  76    of data type <replaceable class="PARAMETER">stype</replaceable>
  77    to hold the current internal state of the aggregate.  At each input
  78    data item,
  79    the state transition function is invoked to calculate a new
  80    internal state value.  After all the data has been processed,
  81    the final function is invoked once to calculate the aggregate's return
  82    value.  If there is no final function then the ending state value
  83    is returned as-is.
  84   </para>
  85
  86   <para>
  87    An aggregate function may provide an initial condition,
  88    that is, an initial value for the internal state value.
  89    This is specified and stored in the database as a column of type
  90    <type>text</type>, but it must be a valid external representation
  91    of a constant of the state value data type.  If it is not supplied
  92    then the state value starts out null.
  93   </para>
  94
  95   <para>
  96    If the state transition function is declared <quote>strict</quote>,
  97    then it cannot be called with null inputs.  With such a transition
  98    function, aggregate execution behaves as follows.  Null input values
  99    are ignored (the function is not called and the previous state value
 100    is retained).  If the initial state value is null, then the first
 101    nonnull input value replaces the state value, and the transition
 102    function is invoked beginning with the second nonnull input value.
 103    This is handy for implementing aggregates like <function>max</function>.
 104    Note that this behavior is only available when
 105    <replaceable class="PARAMETER">state_data_type</replaceable>
 106    is the same as
 107    <replaceable class="PARAMETER">input_data_type</replaceable>.
 108    When these types are different, you must supply a nonnull initial
 109    condition or use a nonstrict transition function.
 110   </para>
 111
 112   <para>
 113    If the state transition function is not strict, then it will be called
 114    unconditionally at each input value, and must deal with null inputs
 115    and null transition values for itself.  This allows the aggregate
 116    author to have full control over the aggregate's handling of null values.
 117   </para>
 118
 119   <para>
 120    If the final function is declared <quote>strict</quote>, then it will not
 121    be called when the ending state value is null; instead a null result
 122    will be returned automatically.  (Of course this is just the normal
 123    behavior of strict functions.)  In any case the final function has
 124    the option of returning a null value.  For example, the final function for
 125    <function>avg</function> returns null when it sees there were zero
 126    input rows.
 127   </para>
 128  </refsect1>
 129
 130  <refsect1>
 131   <title>Parameters</title>
 132
 133   <variablelist>
 134    <varlistentry>
 135     <term><replaceable class="PARAMETER">name</replaceable></term>
 136     <listitem>
 137      <para>
 138       The name (optionally schema-qualified) of the aggregate function
 139       to create.
 140      </para>
 141     </listitem>
 142    </varlistentry>
 143
 144    <varlistentry>
 145     <term><replaceable class="PARAMETER">input_data_type</replaceable></term>
 146     <listitem>
 147      <para>
 148       The input data type on which this aggregate function operates.
 149       This can be specified as <literal>"ANY"</> for an aggregate that
 150       does not examine its input values (an example is
 151       <function>count(*)</function>).
 152      </para>
 153     </listitem>
 154    </varlistentry>
 155
 156    <varlistentry>
 157     <term><replaceable class="PARAMETER">sfunc</replaceable></term>
 158     <listitem>
 159      <para>
 160       The name of the state transition function to be called for each
 161       input data value.  This is normally a function of two arguments,
 162       the first being of type <replaceable
 163       class="PARAMETER">state_data_type</replaceable> and the second
 164       of type <replaceable
 165       class="PARAMETER">input_data_type</replaceable>.  Alternatively,
 166       for an aggregate that does not examine its input values, the
 167       function takes just one argument of type <replaceable
 168       class="PARAMETER">state_data_type</replaceable>.  In either case
 169       the function must return a value of type <replaceable
 170       class="PARAMETER">state_data_type</replaceable>.  This function
 171       takes the current state value and the current input data item,
 172       and returns the next state value.
 173      </para>
 174     </listitem>
 175    </varlistentry>
 176
 177    <varlistentry>
 178     <term><replaceable class="PARAMETER">state_data_type</replaceable></term>
 179     <listitem>
 180      <para>
 181       The data type for the aggregate's state value.
 182      </para>
 183     </listitem>
 184    </varlistentry>
 185
 186    <varlistentry>
 187     <term><replaceable class="PARAMETER">ffunc</replaceable></term>
 188     <listitem>
 189      <para>
 190       The name of the final function called to compute the aggregate's
 191       result after all input data has been traversed.  The function
 192       must take a single argument of type <replaceable
 193       class="PARAMETER">state_data_type</replaceable>.  The return
 194       data type of the aggregate is defined as the return type of this
 195       function.  If <replaceable class="PARAMETER">ffunc</replaceable>
 196       is not specified, then the ending state value is used as the
 197       aggregate's result, and the return type is <replaceable
 198       class="PARAMETER">state_data_type</replaceable>.
 199      </para>
 200     </listitem>
 201    </varlistentry>
 202
 203    <varlistentry>
 204     <term><replaceable class="PARAMETER">initial_condition</replaceable></term>
 205     <listitem>
 206      <para>
 207       The initial setting for the state value.  This must be a string
 208       constant in the form accepted for the data type <replaceable
 209       class="PARAMETER">state_data_type</replaceable>.  If not
 210       specified, the state value starts out null.
 211      </para>
 212     </listitem>
 213    </varlistentry>
 214   </variablelist>
 215
 216   <para>
 217    The parameters of <command>CREATE AGGREGATE</command> can be
 218    written in any order, not just the order illustrated above.
 219   </para>
 220  </refsect1>
 221
 222  <refsect1>
 223   <title>Examples</title>
 224
 225   <para>
 226    See <xref linkend="xaggr">.
 227   </para>
 228  </refsect1>
 229
 230  <refsect1>
 231   <title>Compatibility</title>
 232
 233   <para>
 234    <command>CREATE AGGREGATE</command> is a
 235    <productname>PostgreSQL</productname> language extension.  The SQL
 236    standard does not provide for user-defined aggregate functions.
 237   </para>
 238  </refsect1>
 239
 240  <refsect1>
 241   <title>See Also</title>
 242
 243   <simplelist type="inline">
 244    <member><xref linkend="sql-alteraggregate" endterm="sql-alteraggregate-title"></member>
 245    <member><xref linkend="sql-dropaggregate" endterm="sql-dropaggregate-title"></member>
 246   </simplelist>
 247  </refsect1>
 248 </refentry>
 249
 250 <!-- Keep this comment at the end of the file
 251 Local variables:
 252 mode: sgml
 253 sgml-omittag:nil
 254 sgml-shorttag:t
 255 sgml-minimize-attributes:nil
 256 sgml-always-quote-attributes:t
 257 sgml-indent-step:1
 258 sgml-indent-data:t
 259 sgml-parent-document:nil
 260 sgml-default-dtd-file:"../reference.ced"
 261 sgml-exposed-tags:nil
 262 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 263 sgml-local-ecat-files:nil
 264 End:
 265 -->