diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/create_aggregate.sgml | 37 | ||||
| -rw-r--r-- | doc/src/sgml/xaggr.sgml | 31 |
2 files changed, 47 insertions, 21 deletions
diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index 70362f65039..5eb0741c9c2 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.33 2005/11/04 23:14:02 petere Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.34 2006/04/15 17:45:18 tgl Exp $ PostgreSQL documentation --> @@ -20,8 +20,18 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> +CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( <replaceable class="PARAMETER">input_data_type</replaceable> ) ( + SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, + STYPE = <replaceable class="PARAMETER">state_data_type</replaceable> + [ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ] + [ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ] + [ , SORTOP = <replaceable class="PARAMETER">sort_operator</replaceable> ] +) + +or the old syntax + CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( - BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>, + BASETYPE = <replaceable class="PARAMETER">base_type</replaceable>, SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, STYPE = <replaceable class="PARAMETER">state_data_type</replaceable> [ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ] @@ -87,7 +97,7 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( <para> An aggregate function may provide an initial condition, that is, an initial value for the internal state value. - This is specified and stored in the database as a column of type + This is specified and stored in the database as a value of type <type>text</type>, but it must be a valid external representation of a constant of the state value data type. If it is not supplied then the state value starts out null. @@ -146,8 +156,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; Ordinarily, a data type's <literal><</> operator is the proper sort operator for <function>MIN</>, and <literal>></> is the proper sort operator for <function>MAX</>. Note that the optimization will never - actually take effect unless the specified operator is the <quote>less than</quote> or - <quote>greater than</quote> strategy member of a B-tree index operator class. + actually take effect unless the specified operator is the <quote>less + than</quote> or <quote>greater than</quote> strategy member of a B-tree + index operator class. </para> </refsect1> @@ -170,7 +181,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> The input data type on which this aggregate function operates. - This can be specified as <literal>"ANY"</> for an aggregate that + This can be specified as <literal>*</> for an aggregate that does not examine its input values (an example is <function>count(*)</function>). </para> @@ -178,6 +189,20 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </varlistentry> <varlistentry> + <term><replaceable class="PARAMETER">base_type</replaceable></term> + <listitem> + <para> + In the old syntax for <command>CREATE AGGREGATE</>, the input data type + is specified by a <literal>basetype</> parameter rather than being + written next to the aggregate name. Note that this syntax allows + only one input parameter. To define an aggregate that does not examine + its input values, specify the <literal>basetype</> as + <literal>"ANY"</> (not <literal>*</>). + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable class="PARAMETER">sfunc</replaceable></term> <listitem> <para> diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml index bbb4055b916..db6c077cbf6 100644 --- a/doc/src/sgml/xaggr.sgml +++ b/doc/src/sgml/xaggr.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/xaggr.sgml,v 1.30 2006/03/10 19:10:49 momjian Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/xaggr.sgml,v 1.31 2006/04/15 17:45:33 tgl Exp $ --> <sect1 id="xaggr"> <title>User-Defined Aggregates</title> @@ -43,23 +43,24 @@ The aggregate definition would be: <screen> -CREATE AGGREGATE complex_sum ( +CREATE AGGREGATE sum (complex) +( sfunc = complex_add, - basetype = complex, stype = complex, initcond = '(0,0)' ); -SELECT complex_sum(a) FROM test_complex; +SELECT sum(a) FROM test_complex; - complex_sum -------------- + sum +----------- (34,53.9) </screen> - (In practice, we'd just name the aggregate <function>sum</function> and rely on - <productname>PostgreSQL</productname> to figure out which kind - of sum to apply to a column of type <type>complex</type>.) + (Notice that we are relying on function overloading: there is more than + one aggregate named <function>sum</>, but + <productname>PostgreSQL</productname> can figure out which kind + of sum applies to a column of type <type>complex</type>.) </para> <para> @@ -99,9 +100,9 @@ SELECT complex_sum(a) FROM test_complex; looks like: <programlisting> -CREATE AGGREGATE avg ( +CREATE AGGREGATE avg (float8) +( sfunc = float8_accum, - basetype = float8, stype = float8[], finalfunc = float8_avg, initcond = '{0,0}' @@ -116,14 +117,14 @@ CREATE AGGREGATE avg ( See <xref linkend="extend-types-polymorphic"> for an explanation of polymorphic functions. Going a step further, the aggregate function itself may be specified - with a polymorphic base type and state type, allowing a single + with a polymorphic input type and state type, allowing a single aggregate definition to serve for multiple input data types. Here is an example of a polymorphic aggregate: <programlisting> -CREATE AGGREGATE array_accum ( +CREATE AGGREGATE array_accum (anyelement) +( sfunc = array_append, - basetype = anyelement, stype = anyarray, initcond = '{}' ); @@ -167,7 +168,7 @@ SELECT attrelid::regclass, array_accum(atttypid) <programlisting> if (fcinfo->context && IsA(fcinfo->context, AggState)) </programlisting> - One reason for checking this is that when it is true, the left input + One reason for checking this is that when it is true, the first input must be a temporary transition value and can therefore safely be modified in-place rather than allocating a new copy. (This is the <emphasis>only</> case where it is safe for a function to modify a pass-by-reference input.) |