Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit a596db3

Browse files
committed
Improve documentation for combine functions.
David Rowley
1 parent 59a0281 commit a596db3

File tree

2 files changed

+48
-11
lines changed

2 files changed

+48
-11
lines changed

doc/src/sgml/catalogs.sgml

+6
Original file line numberDiff line numberDiff line change
@@ -406,6 +406,12 @@
406406
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
407407
<entry>Final function (zero if none)</entry>
408408
</row>
409+
<row>
410+
<entry><structfield>aggcombinefn</structfield></entry>
411+
<entry><type>regproc</type></entry>
412+
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
413+
<entry>Combine function (zero if none)</entry>
414+
</row>
409415
<row>
410416
<entry><structfield>aggmtransfn</structfield></entry>
411417
<entry><type>regproc</type></entry>

doc/src/sgml/ref/create_aggregate.sgml

+42-11
Original file line numberDiff line numberDiff line change
@@ -108,15 +108,12 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
108108
functions:
109109
a state transition function
110110
<replaceable class="PARAMETER">sfunc</replaceable>,
111-
an optional final calculation function
112-
<replaceable class="PARAMETER">ffunc</replaceable>,
113-
and an optional combine function
114-
<replaceable class="PARAMETER">combinefunc</replaceable>.
111+
and an optional final calculation function
112+
<replaceable class="PARAMETER">ffunc</replaceable>.
115113
These are used as follows:
116114
<programlisting>
117115
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-values ) ---> next-internal-state
118116
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
119-
<replaceable class="PARAMETER">combinefunc</replaceable>( internal-state, internal-state ) ---> next-internal-state
120117
</programlisting>
121118
</para>
122119

@@ -133,12 +130,6 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
133130
is returned as-is.
134131
</para>
135132

136-
<para>
137-
An aggregate function may also supply a combining function, which allows
138-
the aggregation process to be broken down into multiple steps. This
139-
facilitates query optimization techniques such as parallel query.
140-
</para>
141-
142133
<para>
143134
An aggregate function can provide an initial condition,
144135
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;
405396
</listitem>
406397
</varlistentry>
407398

399+
<varlistentry>
400+
<term><replaceable class="PARAMETER">combinefunc</replaceable></term>
401+
<listitem>
402+
<para>
403+
The <replaceable class="PARAMETER">combinefunc</replaceable> may
404+
optionally be specified in order to allow the aggregate function to
405+
support partial aggregation. This is a prerequisite to allow the
406+
aggregate to participate in certain optimizations such as parallel
407+
aggregation.
408+
</para>
409+
410+
<para>
411+
This function can be thought of as an <replaceable class="PARAMETER">
412+
sfunc</replaceable>, where instead of acting upon individual input rows
413+
and adding these to the aggregate state, it adds other aggregate states
414+
to the aggregate state.
415+
</para>
416+
417+
<para>
418+
The <replaceable class="PARAMETER">combinefunc</replaceable> must accept
419+
two arguments of <replaceable class="PARAMETER">state_data_type
420+
</replaceable> and return <replaceable class="PARAMETER">state_data_type
421+
</replaceable>. Optionally this function may be <quote>strict</quote>. In
422+
this case the function will not be called when either of the input states
423+
are null.
424+
</para>
425+
426+
<para>
427+
For aggregate functions with an <literal>INTERNAL</literal>
428+
<replaceable class="PARAMETER">state_data_type</replaceable> the
429+
<replaceable class="PARAMETER">combinefunc</replaceable> must not be
430+
<quote>strict</quote>. In this scenario the
431+
<replaceable class="PARAMETER">combinefunc</replaceable> must take charge
432+
and ensure that the null states are handled correctly and that the state
433+
being returned is a pointer to memory which belongs in the aggregate
434+
memory context.
435+
</para>
436+
</listitem>
437+
</varlistentry>
438+
408439
<varlistentry>
409440
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
410441
<listitem>

0 commit comments

Comments
 (0)