From: Robert Haas Date: Thu, 24 Mar 2016 16:59:18 +0000 (-0400) Subject: Improve documentation for combine functions. X-Git-Tag: REL9_6_BETA1~402 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a596db332b8c7f593a82af86f69353ba08f6214c;p=postgresql Improve documentation for combine functions. David Rowley --- diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 951f59b76c..4a0ede6a72 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -406,6 +406,12 @@ pg_proc.oid Final function (zero if none) + + aggcombinefn + regproc + pg_proc.oid + Combine function (zero if none) + aggmtransfn regproc diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index 4bda23ada6..837b83c00b 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -108,15 +108,12 @@ CREATE AGGREGATE name ( functions: a state transition function sfunc, - an optional final calculation function - ffunc, - and an optional combine function - combinefunc. + and an optional final calculation function + ffunc. These are used as follows: sfunc( internal-state, next-data-values ) ---> next-internal-state ffunc( internal-state ) ---> aggregate-value -combinefunc( internal-state, internal-state ) ---> next-internal-state @@ -133,12 +130,6 @@ CREATE AGGREGATE name ( is returned as-is. - - 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. - - An aggregate function can provide an initial condition, that is, an initial value for the internal state value. @@ -405,6 +396,46 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; + + combinefunc + + + The combinefunc 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. + + + + This function can be thought of as an + sfunc, where instead of acting upon individual input rows + and adding these to the aggregate state, it adds other aggregate states + to the aggregate state. + + + + The combinefunc must accept + two arguments of state_data_type + and return state_data_type + . Optionally this function may be strict. In + this case the function will not be called when either of the input states + are null. + + + + For aggregate functions with an INTERNAL + state_data_type the + combinefunc must not be + strict. In this scenario the + combinefunc 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. + + + + initial_condition