1 files changed, 94 insertions, 0 deletions
diff --git a/doc/man/create_aggregate.l b/doc/man/create_aggregate.l
new file mode 100644
index 00000000000..645c54f8a51
--- /dev/null
+++ b/doc/man/create_aggregate.l
@@ -0,0 +1,94 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_aggregate.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
+.TH "CREATE AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create aggregate \(em define a new aggregate
+.SH SYNOPSIS
+.nf
+\fBcreate aggregate\fR agg-name [\fBas\fR]
+	\fB(\fP[\fBsfunc1\fR \fB=\fR state-transition-function-1
+	  ,\fP \fBbasetype\fR \fB=\fR data-type
+	  ,\fP \fBstype1\fR \fB=\fR sfunc1-return-type]
+	 [\fB,\fP \fBsfunc2\fR \fB=\fR state-transition-function-2
+	  ,\fP \fBstype2\fR \fB=\fR sfunc2-return-type]
+	 [\fB,\fP \fBfinalfunc\fR \fB=\fR final-function]
+	 [\fB,\fP \fBinitcond1\fR \fB=\fR initial-condition-1]
+	 [\fB,\fP \fBinitcond2\fR \fB=\fR initial-condition-2]\fB)\fR
+.fi
+.SH DESCRIPTION
+An aggregate function can use up to three functions, two
+.IR "state transition"
+functions, X1 and X2:
+.nf
+X1( internal-state1, next-data_item ) ---> next-internal-state1
+X2( internal-state2 ) ---> next-internal-state2
+.fi
+and a
+.BR "final calculation"
+function, F:
+.nf
+F(internal-state1, internal-state2) ---> aggregate-value
+.fi
+These functions are required to have the following properties:
+.IP
+The arguments to state-transition-function-1 must be
+.BR ( stype1 , basetype ) ,
+and its return value must be stype1.
+.IP
+The argument and return value of state-transition-function-2 must be
+.BR stype2 .
+.IP
+The arguments to the final-calculation-function must be
+.BR ( stype1 , stype2 ) ,
+and its return value must be a POSTGRES base type (not
+necessarily the same as basetype.
+.IP
+The final-calculation-function should be specified if and only if both
+state-transition functions are specified.
+.PP
+Note that it is possible to specify aggregate functions that have
+varying combinations of state and final functions.  For example, the
+\*(lqcount\*(rq aggregate requires
+.BR sfunc2
+(an incrementing function) but not
+.BR sfunc1 " or " finalfunc ,
+whereas the \*(lqsum\*(rq aggregate requires
+.BR sfunc1
+(an addition function) but not
+.BR sfunc2 " or " finalfunc
+and the \*(lqaverage\*(rq aggregate requires both of the above state
+functions as well as a
+.BR finalfunc
+(a division function) to produce its answer.  In any case, at least
+one state function must be defined, and any
+.BR sfunc2
+must have a corresponding 
+.BR initcond2 .
+.PP
+Aggregates also require two initial conditions, one for each
+transition function.  These are specified and stored in the database
+as fields of type
+.IR text .
+.SH EXAMPLE
+This
+.IR avg
+aggregate consists of two state transition functions, a addition
+function and a incrementing function.  These modify the internal state
+of the aggregate through a running sum and and the number of values
+seen so far.  It accepts a new employee salary, increments the count,
+and adds the new salary to produce the next state.  The state
+transition functions must be passed correct initialization values.
+The final calculation then divides the sum by the count to produce the
+final answer.
+.nf
+--
+--Create an aggregate for int4 average
+--
+create aggregate avg (sfunc1 = int4add, basetype = int4,
+     stype1 = int4, sfunc2 = int4inc, stype2 = int4,
+     finalfunc = int4div, initcond1 = "0", initcond2 = "0")
+.fi
+.SH "SEE ALSO"
+create function(l),
+remove aggregate(l).