The fact that a final function may be called
multiple times does not appear to be mentioned
in the docs, and a reasonable reading of the
docs gives the alternate impression. For
people writing final functions in C, there
should be some warning about changing the
transition value, such as exists in the comments
in src/backend/executor/nodeWindowAgg.c
I'm not sure if this warning should be placed
in the docs of the CREATE AGGREGATE command, or
in section 35.10. The documentation for the
CREATE AGGREGATE command talks more about what
final functions do, and hence is the more natural
placement in that sense, but for users who are
not doing C programming, changing the state of
the transition value is probably not a problem.
WIP WIP WIP WIP WIP
diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml
index d15fcba..d4603cc 100644
--- a/doc/src/sgml/ref/create_aggregate.sgml
+++ b/doc/src/sgml/ref/create_aggregate.sgml
@@ -111,6 +111,12 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
</para>
<para>
+ The final function may be invoked at other times during the processing
+ of all rows and must not damage the internal state value. It is unwise
+ to assume that the final function will only be invoked once.
+ </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
