← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/create_aggregate.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
-->