head	1.5;
access;
symbols
	REL7_2_8:1.4
	REL7_2_7:1.4
	REL7_2_6:1.4
	REL7_2_5:1.4
	REL7_2_4:1.4
	REL7_2_3:1.4
	REL7_2_STABLE:1.4.0.6
	REL7_2:1.4
	REL7_2_RC2:1.4
	REL7_2_RC1:1.4
	REL7_2_BETA5:1.4
	REL7_2_BETA4:1.4
	REL7_2_BETA3:1.4
	REL7_2_BETA2:1.4
	REL7_2_BETA1:1.4
	REL7_1_2:1.4
	REL7_1_STABLE:1.4.0.4
	REL7_1_BETA:1.4
	REL7_1_BETA3:1.4
	REL7_1_BETA2:1.4
	REL7_1:1.4
	REL7_0_PATCHES:1.4.0.2
	REL7_0:1.4
	REL6_5_PATCHES:1.1.0.2;
locks; strict;
comment	@# @;


1.5
date	2002.08.30.16.48.43;	author momjian;	state dead;
branches;
next	1.4;

1.4
date	99.10.30.16.18.50;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	99.10.30.16.01.13;	author momjian;	state dead;
branches;
next	1.2;

1.2
date	99.09.20.22.30.47;	author scrappy;	state Exp;
branches;
next	1.1;

1.1
date	99.09.13.18.47.30;	author momjian;	state dead;
branches
	1.1.2.1;
next	;

1.1.2.1
date	99.09.13.18.47.30;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.5
log
@Remove pgaccess from CVS.  It has its own home now.
@
text
@.pgaw:Help.f.t insert end "CREATE AGGREGATE" {bold} " allows a user or programmer to extend Postgres functionality by defining new aggregate functions. Some aggregate functions for base types such as \
min\(int4\) and avg(float8) are already provided in the base distribution. If one defines new types or needs an aggregate function not already provided then CREATE AGGREGATE can be used to provide \
the desired features. 

An aggregate function can require up to three functions, two state transition functions, sfunc1 and sfunc2: 
    sfunc1( internal-state1, next-data_item ) ---> next-internal-state1
    sfunc2( internal-state2 ) ---> next-internal-state2   

and a final calculation function, ffunc: 

    ffunc(internal-state1, internal-state2) ---> aggregate-value   

Postgres creates up to two temporary variables (referred to here as temp1 and temp2) to hold intermediate results used as arguments to the transition functions. 

These transition functions are required to have the following properties: 

       The arguments to sfunc1 must be temp1 of type sfunc1_return_type and column_value of type data_type. The return value must be of type sfunc1_return_type and will be used as
       the first argument in the next call to sfunc1. 

       The argument and return value of sfunc2 must be temp2 of type sfunc2_return_type. 

       The arguments to the final-calculation-function must be temp1 and temp2 and its return value must be a Postgres base type (not necessarily data_type which had been specified for
       BASETYPE). 

       FINALFUNC should be specified if and only if both state-transition functions are specified. 

An aggregate function may also require one or two initial conditions, one for each transition function. These are specified and stored in the database as fields of type text. 

" {} "Synopsis" {bold} "
" {} "
CREATE AGGREGATE name \[ AS \]
    ( BASETYPE    = data_type
    \[ , SFUNC1    = sfunc1
      , STYPE1    = sfunc1_return_type \]
    \[ , SFUNC2    = sfunc2
      , STYPE2    = sfunc2_return_type \]
    \[ , FINALFUNC = ffunc \]
    \[ , INITCOND1 = initial_condition1 \]
    \[ , INITCOND2 = initial_condition2 \]
    )

" {code} "Inputs" {bold} "

" {} "name" {italic} "
       The name of an aggregate function to create. 

" {} "data_type" {italic} "
       The fundamental data type on which this aggregate function operates. 

" {} "sfunc1" {italic} "
       The state transition function to be called for every non-NULL field from the source column. It takes a variable of type sfunc1_return_type as the first argument and that field as the
       second argument. 

" {} "sfunc1_return_type" {italic} "
       The return type of the first transition function. 

" {} "sfunc2" {italic} "
       The state transition function to be called for every non-NULL field from the source column. It takes a variable of type sfunc2_return_type as the only argument and returns a variable
       of the same type. 

" {} "sfunc2_return_type" {italic} "
       The return type of the second transition function. 

" {} "ffunc" {italic} "
       The final function called after traversing all input fields. This function must take two arguments of types sfunc1_return_type and sfunc2_return_type. 

" {} "initial_condition1" {italic} "
       The initial value for the first transition function argument. 

" {} "initial_condition2" {italic} "
       The initial value for the second transition function argument. 

" {} "Outputs" {bold} "

" {} "CREATE" {italic} "

       Message returned if the command completes successfully.

" {} "Usage" {bold} "

Refer to the chapter on aggregate functions in the PostgreSQL Programmer's Guide on aggregate functions for complete examples of usage. 

" {} "Notes" {bold} "

Use " {} "DROP AGGREGATE" {bold} " to drop aggregate functions. 

It is possible to specify aggregate functions that have varying combinations of state and final functions. For example, the count aggregate requires SFUNC2 (an incrementing function) but not \
SFUNC1 or FINALFUNC, whereas the sum aggregate requires SFUNC1 (an addition function) but not SFUNC2 or FINALFUNC and the avg aggregate requires both of the above state \
functions as well as a FINALFUNC (a division function) to produce its answer. In any case, at least one state function must be defined, and any SFUNC2 must have a corresponding \
INITCOND2."
@


1.4
log
@Add 0.98.
@
text
@@


1.3
log
@Remove 0.96 for update to 0.98
@
text
@@


1.2
log
@
bring it all into -current again
@
text
@@


1.1
log
@file create_aggregate.hlp was initially added on branch REL6_5_PATCHES.
@
text
@d1 90
@


1.1.2.1
log
@Update pgaccess 0.98
@
text
@a0 90
.pgaw:Help.f.t insert end "CREATE AGGREGATE" {bold} " allows a user or programmer to extend Postgres functionality by defining new aggregate functions. Some aggregate functions for base types such as \
min\(int4\) and avg(float8) are already provided in the base distribution. If one defines new types or needs an aggregate function not already provided then CREATE AGGREGATE can be used to provide \
the desired features. 

An aggregate function can require up to three functions, two state transition functions, sfunc1 and sfunc2: 
    sfunc1( internal-state1, next-data_item ) ---> next-internal-state1
    sfunc2( internal-state2 ) ---> next-internal-state2   

and a final calculation function, ffunc: 

    ffunc(internal-state1, internal-state2) ---> aggregate-value   

Postgres creates up to two temporary variables (referred to here as temp1 and temp2) to hold intermediate results used as arguments to the transition functions. 

These transition functions are required to have the following properties: 

       The arguments to sfunc1 must be temp1 of type sfunc1_return_type and column_value of type data_type. The return value must be of type sfunc1_return_type and will be used as
       the first argument in the next call to sfunc1. 

       The argument and return value of sfunc2 must be temp2 of type sfunc2_return_type. 

       The arguments to the final-calculation-function must be temp1 and temp2 and its return value must be a Postgres base type (not necessarily data_type which had been specified for
       BASETYPE). 

       FINALFUNC should be specified if and only if both state-transition functions are specified. 

An aggregate function may also require one or two initial conditions, one for each transition function. These are specified and stored in the database as fields of type text. 

" {} "Synopsis" {bold} "
" {} "
CREATE AGGREGATE name \[ AS \]
    ( BASETYPE    = data_type
    \[ , SFUNC1    = sfunc1
      , STYPE1    = sfunc1_return_type \]
    \[ , SFUNC2    = sfunc2
      , STYPE2    = sfunc2_return_type \]
    \[ , FINALFUNC = ffunc \]
    \[ , INITCOND1 = initial_condition1 \]
    \[ , INITCOND2 = initial_condition2 \]
    )

" {code} "Inputs" {bold} "

" {} "name" {italic} "
       The name of an aggregate function to create. 

" {} "data_type" {italic} "
       The fundamental data type on which this aggregate function operates. 

" {} "sfunc1" {italic} "
       The state transition function to be called for every non-NULL field from the source column. It takes a variable of type sfunc1_return_type as the first argument and that field as the
       second argument. 

" {} "sfunc1_return_type" {italic} "
       The return type of the first transition function. 

" {} "sfunc2" {italic} "
       The state transition function to be called for every non-NULL field from the source column. It takes a variable of type sfunc2_return_type as the only argument and returns a variable
       of the same type. 

" {} "sfunc2_return_type" {italic} "
       The return type of the second transition function. 

" {} "ffunc" {italic} "
       The final function called after traversing all input fields. This function must take two arguments of types sfunc1_return_type and sfunc2_return_type. 

" {} "initial_condition1" {italic} "
       The initial value for the first transition function argument. 

" {} "initial_condition2" {italic} "
       The initial value for the second transition function argument. 

" {} "Outputs" {bold} "

" {} "CREATE" {italic} "

       Message returned if the command completes successfully.

" {} "Usage" {bold} "

Refer to the chapter on aggregate functions in the PostgreSQL Programmer's Guide on aggregate functions for complete examples of usage. 

" {} "Notes" {bold} "

Use " {} "DROP AGGREGATE" {bold} " to drop aggregate functions. 

It is possible to specify aggregate functions that have varying combinations of state and final functions. For example, the count aggregate requires SFUNC2 (an incrementing function) but not \
SFUNC1 or FINALFUNC, whereas the sum aggregate requires SFUNC1 (an addition function) but not SFUNC2 or FINALFUNC and the avg aggregate requires both of the above state \
functions as well as a FINALFUNC (a division function) to produce its answer. In any case, at least one state function must be defined, and any SFUNC2 must have a corresponding \
INITCOND2."
@
