Improve documentation for combine functions.

David Rowley

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 951f59b76c1f196424d437d2f57b8b2a6ecbde2b..4a0ede6a72c515a9bccb78013ac97e69e72d64ef 100644 (file)
--- 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 4bda23ada6951ad05b1303cb32cc3f8dba3cb038..837b83c00b82fc055c7e45d45a42bdbba77172f1 100644 (file)
--- 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