mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve user-defined-aggregates documentation.

Browse Source 
On closer inspection, that two-element initcond value seems to have been
a little white lie to avoid explaining the full behavior of float8_accum.
But if people are going to expect the examples to be exactly correct,
I suppose we'd better explain.  Per comment from Thom Brown.
This commit is contained in:
Tom Lane 2011-03-23 16:57:33 -04:00
parent e39d6db39b
commit 3b02cef295
1 changed files with 11 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/src/sgml/xaggr.sgml
View File

@ -70,7 +70,7 @@ SELECT sum(a) FROM test_complex;
expects <function>sum</function> to behave that way. We can do this simply by expects <function>sum</function> to behave that way. We can do this simply by
omitting the <literal>initcond</literal> phrase, so that the initial state omitting the <literal>initcond</literal> phrase, so that the initial state
condition is null. Ordinarily this would mean that the <literal>sfunc</literal> condition is null. Ordinarily this would mean that the <literal>sfunc</literal>
would need to check for a null state-condition input, but for would need to check for a null state-condition input. But for
<function>sum</function> and some other simple aggregates like <function>sum</function> and some other simple aggregates like
<function>max</> and <function>min</>, <function>max</> and <function>min</>,
it is sufficient to insert the first nonnull input value into it is sufficient to insert the first nonnull input value into
@ -95,8 +95,8 @@ SELECT sum(a) FROM test_complex;
It requires It requires
two pieces of running state: the sum of the inputs and the count two pieces of running state: the sum of the inputs and the count
of the number of inputs. The final result is obtained by dividing of the number of inputs. The final result is obtained by dividing
these quantities. Average is typically implemented by using a these quantities. Average is typically implemented by using an
two-element array as the state value. For example, array as the state value. For example,
the built-in implementation of <function>avg(float8)</function> the built-in implementation of <function>avg(float8)</function>
looks like: looks like:
@ -109,6 +109,11 @@ CREATE AGGREGATE avg (float8)
initcond = '{0,0,0}' initcond = '{0,0,0}'
); );
</programlisting> </programlisting>
(<function>float8_accum</> requires a three-element array, not just
two elements, because it accumulates the sum of squares as well as
the sum and count of the inputs. This is so that it can be used for
some other aggregates besides <function>avg</>.)
</para> </para>
<para> <para>
@ -178,12 +183,13 @@ SELECT attrelid::regclass, array_accum(atttypid::regtype)
One reason for checking this is that when it is true for a transition One reason for checking this is that when it is true for a transition
function, the first input function, the first input
must be a temporary transition value and can therefore safely be modified 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</> in-place rather than allocating a new copy.
See <literal>int8inc()</> for an example.
(This is the <emphasis>only</>
case where it is safe for a function to modify a pass-by-reference input. case where it is safe for a function to modify a pass-by-reference input.
In particular, aggregate final functions should not modify their inputs in In particular, aggregate final functions should not modify their inputs in
any case, because in some cases they will be re-executed on the same any case, because in some cases they will be re-executed on the same
final transition value.) final transition value.)
See <literal>int8inc()</> for an example.
</para> </para>
<para> <para>