Thread: WIP patch: improve documentation for user defined final functions of aggregates
WIP patch: improve documentation for user defined final functions of aggregates
From
Mark Dilger
Date:
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
Re: WIP patch: improve documentation for user defined final functions of aggregates
From
Tom Lane
Date:
Mark Dilger <markdilger@yahoo.com> writes:
> The fact that a final function may be called
> multiple times does not appear to be mentioned
> in the docs,
It's in xaggr.sgml, near the discussion of AggCheckCallContext
(the end of section 35.10, in current HEAD's section numbering).
In general, people writing C functions should not expect that they
can scribble on pass-by-ref arguments, so I don't see a need to
belabor the point in multiple places.
regards, tom lane