Skip to content

Commit bec98a3

Browse files
tglsfdctglsfdc
committed
Revise aggregate functions per earlier discussions in pghackers.
There's now only one transition value and transition function. NULL handling in aggregates is a lot cleaner. Also, use Numeric accumulators instead of integer accumulators for sum/avg on integer datatypes --- this avoids overflow at the cost of being a little slower. Implement VARIANCE() and STDDEV() aggregates in the standard backend. Also, enable new LIKE selectivity estimators by default. Unrelated change, but as long as I had to force initdb anyway...
1 parent 139f19c commit bec98a3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+1948
-1812
lines changed

‎doc/src/sgml/catalogs.sgml‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.\" This is -*-nroff-*-
22
.\" XXX standard disclaimer belongs here....
3-
.\" $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.6 2000/06/09 01:43:56 momjian Exp $
3+
.\" $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.7 2000/07/17 03:04:40 tgl Exp $
44
.TH "SYSTEM CATALOGS" INTRO 03/13/94 PostgreSQL PostgreSQL
55
.SH "Section 7 - System Catalogs"
66
.de LS
@@ -91,20 +91,16 @@ The following catalogs relate to the class/type system.
9191
* see DEFINE AGGREGATE for an explanation of transition functions
9292
*/
9393
pg_aggregate
94-
NameData aggname /* aggregate name (e.g., "count") */
94+
NameData aggname /* aggregate name (e.g., "count") */
9595
oid aggowner /* usesysid of creator */
96-
regproc aggtransfn1 /* first transition function */
97-
regproc aggtransfn2 /* second transition function */
96+
regproc aggtransfn /* transition function */
9897
regproc aggfinalfn /* final function */
9998
oid aggbasetype /* type of data on which aggregate
10099
operates */
101-
oid aggtranstype1 /* type returned by aggtransfn1 */
102-
oid aggtranstype2 /* type returned by aggtransfn2 */
103-
oid aggfinaltype /* type returned by aggfinalfn */
104-
text agginitval1 /* external format of initial
105-
(starting) value of aggtransfn1 */
106-
text agginitval2 /* external format of initial
107-
(starting) value of aggtransfn2 */
100+
oid aggtranstype /* type of aggregate's transition
101+
(state) data */
102+
oid aggfinaltype /* type of aggregate's final result */
103+
text agginitval /* external format of initial state value */
108104
.fi
109105
.nf M
110106
pg_am

‎doc/src/sgml/ref/create_aggregate.sgml‎

Lines changed: 92 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.9 2000/03/31 14:57:05 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.10 2000/07/17 03:04:41 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -21,20 +21,18 @@ Postgres documentation
2121
</refnamediv>
2222
<refsynopsisdiv>
2323
<refsynopsisdivinfo>
24-
<date>1999-07-20</date>
24+
<date>2000-07-16</date>
2525
</refsynopsisdivinfo>
2626
<synopsis>
27-
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>
28-
[ , SFUNC1 = <replaceable class="PARAMETER">sfunc1</replaceable>, STYPE1 = <replaceable class="PARAMETER">state1_type</replaceable> ]
29-
[ , SFUNC2 = <replaceable class="PARAMETER">sfunc2</replaceable>, STYPE2 = <replaceable class="PARAMETER">state2_type</replaceable> ]
27+
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
28+
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, STYPE = <replaceable class="PARAMETER">state_type</replaceable>
3029
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
31-
[ , INITCOND1 = <replaceable class="PARAMETER">initial_condition1</replaceable> ]
32-
[ , INITCOND2 = <replaceable class="PARAMETER">initial_condition2</replaceable> ] )
30+
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ] )
3331
</synopsis>
3432

3533
<refsect2 id="R2-SQL-CREATEAGGREGATE-1">
3634
<refsect2info>
37-
<date>1998-09-09</date>
35+
<date>2000-07-16</date>
3836
</refsect2info>
3937
<title>
4038
Inputs
@@ -55,57 +53,39 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE =
5553
<listitem>
5654
<para>
5755
The input data type on which this aggregate function operates.
56+
This can be specified as ANY for an aggregate that does not
57+
examine its input values
58+
(an example is <function>count(*)</function>).
5859
</para>
5960
</listitem>
6061
</varlistentry>
6162

6263
<varlistentry>
63-
<term><replaceable class="PARAMETER">sfunc1</replaceable></term>
64+
<term><replaceable class="PARAMETER">sfunc</replaceable></term>
6465
<listitem>
6566
<para>
66-
A state transition function
67-
to be called for every non-NULL input data value.
68-
This must be a function of two arguments, the first being of
69-
type <replaceable class="PARAMETER">state1_type</replaceable>
67+
The name of the state transition function
68+
to be called for each input data value.
69+
This is normally a function of two arguments, the first being of
70+
type <replaceable class="PARAMETER">state_type</replaceable>
7071
and the second of
7172
type <replaceable class="PARAMETER">input_data_type</replaceable>.
72-
The function must return a value of
73-
type <replaceable class="PARAMETER">state1_type</replaceable>.
74-
This function takes the current state value 1 and the current
75-
input data item, and returns the next state value 1.
76-
</para>
77-
</listitem>
78-
</varlistentry>
79-
80-
<varlistentry>
81-
<term><replaceable class="PARAMETER">state1_type</replaceable></term>
82-
<listitem>
83-
<para>
84-
The data type for the first state value of the aggregate.
85-
</para>
86-
</listitem>
87-
</varlistentry>
88-
89-
<varlistentry>
90-
<term><replaceable class="PARAMETER">sfunc2</replaceable></term>
91-
<listitem>
92-
<para>
93-
A state transition function
94-
to be called for every non-NULL input data value.
95-
This must be a function of one argument of
96-
type <replaceable class="PARAMETER">state2_type</replaceable>,
97-
returning a value of the same type.
98-
This function takes the current state value 2 and
99-
returns the next state value 2.
73+
Alternatively, for an aggregate that does not examine its input
74+
values, the function takes just one argument of
75+
type <replaceable class="PARAMETER">state_type</replaceable>.
76+
In either case the function must return a value of
77+
type <replaceable class="PARAMETER">state_type</replaceable>.
78+
This function takes the current state value and the current
79+
input data item, and returns the next state value.
10080
</para>
10181
</listitem>
10282
</varlistentry>
10383

10484
<varlistentry>
105-
<term><replaceable class="PARAMETER">state2_type</replaceable></term>
85+
<term><replaceable class="PARAMETER">state_type</replaceable></term>
10686
<listitem>
10787
<para>
108-
The data type for the second state value of the aggregate.
88+
The data type for the aggregate's state value.
10989
</para>
11090
</listitem>
11191
</varlistentry>
@@ -114,35 +94,28 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE =
11494
<term><replaceable class="PARAMETER">ffunc</replaceable></term>
11595
<listitem>
11696
<para>
117-
The final function called to compute the aggregate's result
118-
after all input data has been traversed.
119-
If both state values are used, the final function must
120-
take two arguments of types
121-
<replaceable class="PARAMETER">state1_type</replaceable>
122-
and
123-
<replaceable class="PARAMETER">state2_type</replaceable>.
124-
If only one state value is used, the final function must
125-
take a single argument of that state value's type.
97+
The name of the final function called to compute the aggregate's
98+
result after all input data has been traversed. The function
99+
must take a single argument of type
100+
<replaceable class="PARAMETER">state_type</replaceable>.
126101
The output datatype of the aggregate is defined as the return
127102
type of this function.
103+
If <replaceable class="PARAMETER">ffunc</replaceable>
104+
is not specified, then the ending state value is used as the
105+
aggregate's result, and the output type is
106+
<replaceable class="PARAMETER">state_type</replaceable>.
128107
</para>
129108
</listitem>
130109
</varlistentry>
131110

132111
<varlistentry>
133-
<term><replaceable class="PARAMETER">initial_condition1</replaceable></term>
112+
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
134113
<listitem>
135114
<para>
136-
The initial value for state value 1.
137-
</para>
138-
</listitem>
139-
</varlistentry>
140-
141-
<varlistentry>
142-
<term><replaceable class="PARAMETER">initial_condition2</replaceable></term>
143-
<listitem>
144-
<para>
145-
The initial value for state value 2.
115+
The initial setting for the state value. This must be a literal
116+
constant in the form accepted for the datatype
117+
<replaceable class="PARAMETER">state_type</replaceable>.
118+
If not specified, the state value starts out NULL.
146119
</para>
147120
</listitem>
148121
</varlistentry>
@@ -177,7 +150,7 @@ CREATE
177150

178151
<refsect1 id="R1-SQL-CREATEAGGREGATE-1">
179152
<refsect1info>
180-
<date>1998-09-09</date>
153+
<date>2000-07-16</date>
181154
</refsect1info>
182155
<title>
183156
Description
@@ -199,65 +172,76 @@ CREATE
199172
of the same name and input data type as an aggregate.
200173
</para>
201174
<para>
202-
An aggregate function is made from between one and three ordinary
175+
An aggregate function is made from one or two ordinary
203176
functions:
204-
two state transition functions,
205-
<replaceable class="PARAMETER">sfunc1</replaceable>
206-
and <replaceable class="PARAMETER">sfunc2</replaceable>,
207-
and a final calculation function,
177+
a state transition function
178+
<replaceable class="PARAMETER">sfunc</replaceable>,
179+
and an optional final calculation function
208180
<replaceable class="PARAMETER">ffunc</replaceable>.
209181
These are used as follows:
210182
<programlisting>
211-
<replaceable class="PARAMETER">sfunc1</replaceable>( internal-state1, next-data-item ) ---> next-internal-state1
212-
<replaceable class="PARAMETER">sfunc2</replaceable>( internal-state2 ) ---> next-internal-state2
213-
<replaceable class="PARAMETER">ffunc</replaceable>(internal-state1, internal-state2) ---> aggregate-value
183+
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
184+
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
214185
</programlisting>
215186
</para>
216187
<para>
217-
<productname>Postgres</productname> creates one or two temporary variables
218-
(of data types <replaceable class="PARAMETER">stype1</replaceable> and/or
219-
<replaceable class="PARAMETER">stype2</replaceable>) to hold the
220-
current internal states of the aggregate. At each input data item,
221-
the state transition function(s) are invoked to calculate new values
222-
for the internal state values. After all the data has been processed,
188+
<productname>Postgres</productname> creates a temporary variable
189+
of data type <replaceable class="PARAMETER">stype</replaceable>
190+
to hold the current internal state of the aggregate. At each input
191+
data item,
192+
the state transition function is invoked to calculate a new
193+
internal state value. After all the data has been processed,
223194
the final function is invoked once to calculate the aggregate's output
224-
value.
195+
value. If there is no final function then the ending state value
196+
is returned as-is.
225197
</para>
198+
226199
<para>
227-
<replaceable class="PARAMETER">ffunc</replaceable> must be specified if
228-
both transition functions are specified. If only one transition function
229-
is used, then <replaceable class="PARAMETER">ffunc</replaceable> is
230-
optional. The default behavior when
231-
<replaceable class="PARAMETER">ffunc</replaceable> is not provided is
232-
to return the ending value of the internal state value being used
233-
(and, therefore, the aggregate's output type is the same as that
234-
state value's type).
235-
</para>
200+
An aggregate function may provide an initial condition,
201+
that is, an initial value for the internal state value.
202+
This is specified and stored in the database as a field of type
203+
<type>text</type>, but it must be a valid external representation
204+
of a constant of the state value datatype. If it is not supplied
205+
then the state value starts out NULL.
206+
</para>
236207

237-
<para>
238-
An aggregate function may also provide one or two initial conditions,
239-
that is, initial values for the internal state values being used.
240-
These are specified and stored in the database as fields of type
241-
<type>text</type>, but they must be valid external representations
242-
of constants of the state value datatypes. If
243-
<replaceable class="PARAMETER">sfunc1</replaceable> is specified
244-
without an <replaceable class="PARAMETER">initcond1</replaceable> value,
245-
then the system does not call
246-
<replaceable class="PARAMETER">sfunc1</replaceable>
247-
at the first input item; instead, the internal state value 1 is
248-
initialized with the first input value, and
249-
<replaceable class="PARAMETER">sfunc1</replaceable> is called beginning
250-
at the second input item. This is useful for aggregates like MIN and
251-
MAX. Note that an aggregate using this feature will return NULL when
252-
called with no input values. There is no comparable provision for
253-
state value 2; if <replaceable class="PARAMETER">sfunc2</replaceable> is
254-
specified then an <replaceable class="PARAMETER">initcond2</replaceable> is
255-
required.
208+
<para>
209+
If the state transition function is declared "strict" in pg_proc,
210+
then it cannot be called with NULL inputs. With such a transition
211+
function, aggregate execution behaves as follows. NULL input values
212+
are ignored (the function is not called and the previous state value
213+
is retained). If the initial state value is NULL, then the first
214+
non-NULL input value replaces the state value, and the transition
215+
function is invoked beginning with the second non-NULL input value.
216+
This is handy for implementing aggregates like <function>max</function>.
217+
Note that this behavior is only available when
218+
<replaceable class="PARAMETER">state_type</replaceable>
219+
is the same as
220+
<replaceable class="PARAMETER">input_data_type</replaceable>.
221+
When these types are different, you must supply a non-NULL initial
222+
condition or use a non-strict transition function.
223+
</para>
224+
225+
<para>
226+
If the state transition function is not strict, then it will be called
227+
unconditionally at each input value, and must deal with NULL inputs
228+
and NULL transition values for itself. This allows the aggregate
229+
author to have full control over the aggregate's handling of NULLs.
230+
</para>
231+
232+
<para>
233+
If the final function is declared "strict", then it will not
234+
be called when the ending state value is NULL; instead a NULL result
235+
will be output automatically. (Of course this is just the normal
236+
behavior of strict functions.) In any case the final function has
237+
the option of returning NULL. For example, the final function for
238+
<function>avg</function> returns NULL when it sees there were zero
239+
input tuples.
256240
</para>
257241

258242
<refsect2 id="R2-SQL-CREATEAGGREGATE-3">
259243
<refsect2info>
260-
<date>1998-09-09</date>
244+
<date>2000-07-16</date>
261245
</refsect2info>
262246
<title>
263247
Notes
@@ -272,29 +256,6 @@ CREATE
272256
in any order, not just the order illustrated above.
273257
</para>
274258

275-
<para>
276-
It is possible to specify aggregate functions
277-
that have varying combinations of state and final functions.
278-
For example, the <function>count</function> aggregate requires
279-
<replaceable class="PARAMETER">sfunc2</replaceable>
280-
(an incrementing function) but not
281-
<replaceable class="PARAMETER">sfunc1</replaceable> or
282-
<replaceable class="PARAMETER">ffunc</replaceable>,
283-
whereas the <function>sum</function> aggregate requires
284-
<replaceable class="PARAMETER">sfunc1</replaceable> (an addition
285-
function) but not <replaceable class="PARAMETER">sfunc2</replaceable> or
286-
<replaceable class="PARAMETER">ffunc</replaceable>, and the
287-
<function>avg</function>
288-
aggregate requires
289-
both state functions as
290-
well as a <replaceable class="PARAMETER">ffunc</replaceable> (a division
291-
function) to produce its
292-
answer. In any case, at least one state function must be
293-
defined, and any <replaceable class="PARAMETER">sfunc2</replaceable> must
294-
have a corresponding
295-
<replaceable class="PARAMETER">initcond2</replaceable>.
296-
</para>
297-
298259
</refsect2>
299260
</refsect1>
300261

‎doc/src/sgml/ref/drop_aggregate.sgml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.7 2000/05/18 14:24:32 momjian Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.8 2000/07/17 03:04:41 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -49,7 +49,7 @@ DROP AGGREGATE <replaceable class="PARAMETER">name</replaceable> <replaceable cl
4949
<para>
5050
The type of an existing aggregate function.
5151
(Refer to the <citetitle>PostgreSQL User's Guide</citetitle> for
52-
further information about data types).
52+
further information about data types.)
5353
<comment>This should become a cross-reference rather than a
5454
hard-coded chapter number</comment>
5555
</para>
@@ -80,7 +80,7 @@ DROP
8080
</varlistentry>
8181
<varlistentry>
8282
<term><computeroutput>
83-
NOTICE RemoveAggregate: aggregate '<replaceable class="parameter">agg</replaceable>' for '<replaceable class="parameter">type</replaceable>' does not exist
83+
ERROR: RemoveAggregate: aggregate '<replaceable class="parameter">agg</replaceable>' for '<replaceable class="parameter">type</replaceable>' does not exist
8484
</computeroutput></term>
8585
<listitem>
8686
<para>

0 commit comments

Comments
 (0)