raw/man7/create_aggregate.7

   1 .\\" auto-generated by docbook2man-spec $Revision: 1.1 $
   2 .TH "CREATE AGGREGATE" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
   3 .SH NAME
   4 CREATE AGGREGATE \- define a new aggregate function
   5
   6 .SH SYNOPSIS
   7 .sp
   8 .nf
   9 CREATE AGGREGATE \fIname\fR (
  10     BASETYPE = \fIinput_data_type\fR,
  11     SFUNC = \fIsfunc\fR,
  12     STYPE = \fIstate_data_type\fR
  13     [ , FINALFUNC = \fIffunc\fR ]
  14     [ , INITCOND = \fIinitial_condition\fR ]
  15 )
  16 .sp
  17 .fi
  18 .SH "DESCRIPTION"
  19 .PP
  20 \fBCREATE AGGREGATE\fR defines a new aggregate function. Some aggregate functions
  21 for base types such as \fBmin(integer)\fR
  22 and \fBavg(double precision)\fR are already provided in the standard
  23 distribution. If one defines new types or needs an aggregate function not
  24 already provided, then \fBCREATE AGGREGATE\fR
  25 can be used to provide the desired features.
  26 .PP
  27 If a schema name is given (for example, CREATE AGGREGATE
  28 myschema.myagg ...) then the aggregate function is created in the
  29 specified schema. Otherwise it is created in the current schema.
  30 .PP
  31 An aggregate function is identified by its name and input data type.
  32 Two aggregates in the same schema can have the same name if they operate on
  33 different input types. The
  34 name and input data type of an aggregate must also be distinct from
  35 the name and input data type(s) of every ordinary function in the same
  36 schema.
  37 .PP
  38 An aggregate function is made from one or two ordinary
  39 functions:
  40 a state transition function
  41 \fIsfunc\fR,
  42 and an optional final calculation function
  43 \fIffunc\fR.
  44 These are used as follows:
  45 .sp
  46 .nf
  47 \fIsfunc\fR( internal-state, next-data-item ) ---> next-internal-state
  48 \fIffunc\fR( internal-state ) ---> aggregate-value
  49 .sp
  50 .fi
  51 .PP
  52 PostgreSQL creates a temporary variable
  53 of data type \fIstype\fR
  54 to hold the current internal state of the aggregate. At each input
  55 data item,
  56 the state transition function is invoked to calculate a new
  57 internal state value. After all the data has been processed,
  58 the final function is invoked once to calculate the aggregate's return
  59 value. If there is no final function then the ending state value
  60 is returned as-is.
  61 .PP
  62 An aggregate function may provide an initial condition,
  63 that is, an initial value for the internal state value.
  64 This is specified and stored in the database as a column of type
  65 \fBtext\fR, but it must be a valid external representation
  66 of a constant of the state value data type. If it is not supplied
  67 then the state value starts out null.
  68 .PP
  69 If the state transition function is declared ``strict'',
  70 then it cannot be called with null inputs. With such a transition
  71 function, aggregate execution behaves as follows. Null input values
  72 are ignored (the function is not called and the previous state value
  73 is retained). If the initial state value is null, then the first
  74 nonnull input value replaces the state value, and the transition
  75 function is invoked beginning with the second nonnull input value.
  76 This is handy for implementing aggregates like \fBmax\fR.
  77 Note that this behavior is only available when
  78 \fIstate_data_type\fR
  79 is the same as
  80 \fIinput_data_type\fR.
  81 When these types are different, you must supply a nonnull initial
  82 condition or use a nonstrict transition function.
  83 .PP
  84 If the state transition function is not strict, then it will be called
  85 unconditionally at each input value, and must deal with null inputs
  86 and null transition values for itself. This allows the aggregate
  87 author to have full control over the aggregate's handling of null values.
  88 .PP
  89 If the final function is declared ``strict'', then it will not
  90 be called when the ending state value is null; instead a null result
  91 will be returned automatically. (Of course this is just the normal
  92 behavior of strict functions.) In any case the final function has
  93 the option of returning a null value. For example, the final function for
  94 \fBavg\fR returns null when it sees there were zero
  95 input rows.
  96 .SH "PARAMETERS"
  97 .TP
  98 \fB\fIname\fB\fR
  99 The name (optionally schema-qualified) of the aggregate function
 100 to create.
 101 .TP
 102 \fB\fIinput_data_type\fB\fR
 103 The input data type on which this aggregate function operates.
 104 This can be specified as "ANY" for an aggregate that
 105 does not examine its input values (an example is
 106 \fBcount(*)\fR).
 107 .TP
 108 \fB\fIsfunc\fB\fR
 109 The name of the state transition function to be called for each
 110 input data value. This is normally a function of two arguments,
 111 the first being of type \fIstate_data_type\fR and the second
 112 of type \fIinput_data_type\fR. Alternatively,
 113 for an aggregate that does not examine its input values, the
 114 function takes just one argument of type \fIstate_data_type\fR. In either case
 115 the function must return a value of type \fIstate_data_type\fR. This function
 116 takes the current state value and the current input data item,
 117 and returns the next state value.
 118 .TP
 119 \fB\fIstate_data_type\fB\fR
 120 The data type for the aggregate's state value.
 121 .TP
 122 \fB\fIffunc\fB\fR
 123 The name of the final function called to compute the aggregate's
 124 result after all input data has been traversed. The function
 125 must take a single argument of type \fIstate_data_type\fR. The return
 126 data type of the aggregate is defined as the return type of this
 127 function. If \fIffunc\fR
 128 is not specified, then the ending state value is used as the
 129 aggregate's result, and the return type is \fIstate_data_type\fR.
 130 .TP
 131 \fB\fIinitial_condition\fB\fR
 132 The initial setting for the state value. This must be a string
 133 constant in the form accepted for the data type \fIstate_data_type\fR. If not
 134 specified, the state value starts out null.
 135 .PP
 136 The parameters of \fBCREATE AGGREGATE\fR can be
 137 written in any order, not just the order illustrated above.
 138 .PP
 139 .SH "EXAMPLES"
 140 .PP
 141 See the section called ``User-defined Aggregates'' in the documentation.
 142 .SH "COMPATIBILITY"
 143 .PP
 144 \fBCREATE AGGREGATE\fR is a
 145 PostgreSQL language extension. The SQL
 146 standard does not provide for user-defined aggregate function.
 147 .SH "SEE ALSO"
 148 ALTER AGGREGATE [\fBalter_aggregate\fR(7)], DROP AGGREGATE [\fBdrop_aggregate\fR(l)]
 149