diff options
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_aggregate.sgml | 53 |
2 files changed, 48 insertions, 11 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 951f59b76c1..4a0ede6a72c 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -407,6 +407,12 @@ <entry>Final function (zero if none)</entry> </row> <row> + <entry><structfield>aggcombinefn</structfield></entry> + <entry><type>regproc</type></entry> + <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> + <entry>Combine function (zero if none)</entry> + </row> + <row> <entry><structfield>aggmtransfn</structfield></entry> <entry><type>regproc</type></entry> <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index 4bda23ada69..837b83c00b8 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -108,15 +108,12 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( functions: a state transition function <replaceable class="PARAMETER">sfunc</replaceable>, - an optional final calculation function - <replaceable class="PARAMETER">ffunc</replaceable>, - and an optional combine function - <replaceable class="PARAMETER">combinefunc</replaceable>. + and an optional final calculation function + <replaceable class="PARAMETER">ffunc</replaceable>. These are used as follows: <programlisting> <replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-values ) ---> next-internal-state <replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value -<replaceable class="PARAMETER">combinefunc</replaceable>( internal-state, internal-state ) ---> next-internal-state </programlisting> </para> @@ -134,12 +131,6 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( </para> <para> - An aggregate function may also supply a combining function, which allows - the aggregation process to be broken down into multiple steps. This - facilitates query optimization techniques such as parallel query. - </para> - - <para> An aggregate function can provide an initial condition, that is, an initial value for the internal state value. This is specified and stored in the database as a value of type @@ -406,6 +397,46 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </varlistentry> <varlistentry> + <term><replaceable class="PARAMETER">combinefunc</replaceable></term> + <listitem> + <para> + The <replaceable class="PARAMETER">combinefunc</replaceable> may + optionally be specified in order to allow the aggregate function to + support partial aggregation. This is a prerequisite to allow the + aggregate to participate in certain optimizations such as parallel + aggregation. + </para> + + <para> + This function can be thought of as an <replaceable class="PARAMETER"> + sfunc</replaceable>, where instead of acting upon individual input rows + and adding these to the aggregate state, it adds other aggregate states + to the aggregate state. + </para> + + <para> + The <replaceable class="PARAMETER">combinefunc</replaceable> must accept + two arguments of <replaceable class="PARAMETER">state_data_type + </replaceable> and return <replaceable class="PARAMETER">state_data_type + </replaceable>. Optionally this function may be <quote>strict</quote>. In + this case the function will not be called when either of the input states + are null. + </para> + + <para> + For aggregate functions with an <literal>INTERNAL</literal> + <replaceable class="PARAMETER">state_data_type</replaceable> the + <replaceable class="PARAMETER">combinefunc</replaceable> must not be + <quote>strict</quote>. In this scenario the + <replaceable class="PARAMETER">combinefunc</replaceable> must take charge + and ensure that the null states are handled correctly and that the state + being returned is a pointer to memory which belongs in the aggregate + memory context. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable class="PARAMETER">initial_condition</replaceable></term> <listitem> <para> |