mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-30 19:11:13 +02:00
0d3f4406df
There's no inherent reason why an aggregate function can't be variadic (even VARIADIC ANY) if its transition function can handle the case. Indeed, this patch to add the feature touches none of the planner or executor, and little of the parser; the main missing stuff was DDL and pg_dump support. It is true that variadic aggregates can create the same sort of ambiguity about parameters versus ORDER BY keys that was complained of when we (briefly) had both one- and two-argument forms of string_agg(). However, the policy formed in response to that discussion only said that we'd not create any built-in aggregates with varying numbers of arguments, not that we shouldn't allow users to do it. So the logical extension of that is we can allow users to make variadic aggregates as long as we're wary about shipping any such in core. In passing, this patch allows aggregate function arguments to be named, to the extent of remembering the names in pg_proc and dumping them in pg_dump. You can't yet call an aggregate using named-parameter notation. That seems like a likely future extension, but it'll take some work, and it's not what this patch is really about. Likewise, there's still some work needed to make window functions handle VARIADIC fully, but I left that for another day. initdb forced because of new aggvariadic field in Aggref parse nodes.
233 lines
8.6 KiB
Plaintext
233 lines
8.6 KiB
Plaintext
<!-- doc/src/sgml/xaggr.sgml -->
|
|
|
|
<sect1 id="xaggr">
|
|
<title>User-defined Aggregates</title>
|
|
|
|
<indexterm zone="xaggr">
|
|
<primary>aggregate function</primary>
|
|
<secondary>user-defined</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
Aggregate functions in <productname>PostgreSQL</productname>
|
|
are expressed in terms of <firstterm>state values</firstterm>
|
|
and <firstterm>state transition functions</firstterm>.
|
|
That is, an aggregate operates using a state value that is updated
|
|
as each successive input row is processed.
|
|
To define a new aggregate
|
|
function, one selects a data type for the state value,
|
|
an initial value for the state, and a state transition
|
|
function. The state transition function is just an
|
|
ordinary function that could also be used outside the
|
|
context of the aggregate. A <firstterm>final function</firstterm>
|
|
can also be specified, in case the desired result of the aggregate
|
|
is different from the data that needs to be kept in the running
|
|
state value.
|
|
</para>
|
|
|
|
<para>
|
|
Thus, in addition to the argument and result data types seen by a user
|
|
of the aggregate, there is an internal state-value data type that
|
|
might be different from both the argument and result types.
|
|
</para>
|
|
|
|
<para>
|
|
If we define an aggregate that does not use a final function,
|
|
we have an aggregate that computes a running function of
|
|
the column values from each row. <function>sum</> is an
|
|
example of this kind of aggregate. <function>sum</> starts at
|
|
zero and always adds the current row's value to
|
|
its running total. For example, if we want to make a <function>sum</>
|
|
aggregate to work on a data type for complex numbers,
|
|
we only need the addition function for that data type.
|
|
The aggregate definition would be:
|
|
|
|
<screen>
|
|
CREATE AGGREGATE sum (complex)
|
|
(
|
|
sfunc = complex_add,
|
|
stype = complex,
|
|
initcond = '(0,0)'
|
|
);
|
|
|
|
SELECT sum(a) FROM test_complex;
|
|
|
|
sum
|
|
-----------
|
|
(34,53.9)
|
|
</screen>
|
|
|
|
(Notice that we are relying on function overloading: there is more than
|
|
one aggregate named <function>sum</>, but
|
|
<productname>PostgreSQL</productname> can figure out which kind
|
|
of sum applies to a column of type <type>complex</type>.)
|
|
</para>
|
|
|
|
<para>
|
|
The above definition of <function>sum</function> will return zero (the initial
|
|
state condition) if there are no nonnull input values.
|
|
Perhaps we want to return null in that case instead — the SQL standard
|
|
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
|
|
condition is null. Ordinarily this would mean that the <literal>sfunc</literal>
|
|
would need to check for a null state-condition input. But for
|
|
<function>sum</function> and some other simple aggregates like
|
|
<function>max</> and <function>min</>,
|
|
it is sufficient to insert the first nonnull input value into
|
|
the state variable and then start applying the transition function
|
|
at the second nonnull input value. <productname>PostgreSQL</productname>
|
|
will do that automatically if the initial condition is null and
|
|
the transition function is marked <quote>strict</> (i.e., not to be called
|
|
for null inputs).
|
|
</para>
|
|
|
|
<para>
|
|
Another bit of default behavior for a <quote>strict</> transition function
|
|
is that the previous state value is retained unchanged whenever a
|
|
null input value is encountered. Thus, null values are ignored. If you
|
|
need some other behavior for null inputs, do not declare your
|
|
transition function as strict; instead code it to test for null inputs and
|
|
do whatever is needed.
|
|
</para>
|
|
|
|
<para>
|
|
<function>avg</> (average) is a more complex example of an aggregate.
|
|
It requires
|
|
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
|
|
these quantities. Average is typically implemented by using an
|
|
array as the state value. For example,
|
|
the built-in implementation of <function>avg(float8)</function>
|
|
looks like:
|
|
|
|
<programlisting>
|
|
CREATE AGGREGATE avg (float8)
|
|
(
|
|
sfunc = float8_accum,
|
|
stype = float8[],
|
|
finalfunc = float8_avg,
|
|
initcond = '{0,0,0}'
|
|
);
|
|
</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>
|
|
Aggregate functions can use polymorphic
|
|
state transition functions or final functions, so that the same functions
|
|
can be used to implement multiple aggregates.
|
|
See <xref linkend="extend-types-polymorphic">
|
|
for an explanation of polymorphic functions.
|
|
Going a step further, the aggregate function itself can be specified
|
|
with polymorphic input type(s) and state type, allowing a single
|
|
aggregate definition to serve for multiple input data types.
|
|
Here is an example of a polymorphic aggregate:
|
|
|
|
<programlisting>
|
|
CREATE AGGREGATE array_accum (anyelement)
|
|
(
|
|
sfunc = array_append,
|
|
stype = anyarray,
|
|
initcond = '{}'
|
|
);
|
|
</programlisting>
|
|
|
|
Here, the actual state type for any aggregate call is the array type
|
|
having the actual input type as elements. The behavior of the aggregate
|
|
is to concatenate all the inputs into an array of that type.
|
|
(Note: the built-in aggregate <function>array_agg</> provides similar
|
|
functionality, with better performance than this definition would have.)
|
|
</para>
|
|
|
|
<para>
|
|
Here's the output using two different actual data types as arguments:
|
|
|
|
<programlisting>
|
|
SELECT attrelid::regclass, array_accum(attname)
|
|
FROM pg_attribute
|
|
WHERE attnum > 0 AND attrelid = 'pg_tablespace'::regclass
|
|
GROUP BY attrelid;
|
|
|
|
attrelid | array_accum
|
|
---------------+---------------------------------------
|
|
pg_tablespace | {spcname,spcowner,spcacl,spcoptions}
|
|
(1 row)
|
|
|
|
SELECT attrelid::regclass, array_accum(atttypid::regtype)
|
|
FROM pg_attribute
|
|
WHERE attnum > 0 AND attrelid = 'pg_tablespace'::regclass
|
|
GROUP BY attrelid;
|
|
|
|
attrelid | array_accum
|
|
---------------+---------------------------
|
|
pg_tablespace | {name,oid,aclitem[],text[]}
|
|
(1 row)
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
An aggregate function can be made to accept a varying number of arguments
|
|
by declaring its last argument as a <literal>VARIADIC</> array, in much
|
|
the same fashion as for regular functions; see
|
|
<xref linkend="xfunc-sql-variadic-functions">. The aggregate's transition
|
|
function must have the same array type as its last argument. The
|
|
transition function typically would also be marked <literal>VARIADIC</>,
|
|
but this is not strictly required.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Variadic aggregates are easily misused in connection with
|
|
the <literal>ORDER BY</> option (see <xref linkend="syntax-aggregates">),
|
|
since the parser cannot tell whether the wrong number of actual arguments
|
|
have been given in such a combination. Keep in mind that everything to
|
|
the right of <literal>ORDER BY</> is a sort key, not an argument to the
|
|
aggregate. For example, in
|
|
<programlisting>
|
|
SELECT myaggregate(a ORDER BY a, b, c) FROM ...
|
|
</programlisting>
|
|
the parser will see this as a single aggregate function argument and
|
|
three sort keys. However, the user might have intended
|
|
<programlisting>
|
|
SELECT myaggregate(a, b, c ORDER BY a) FROM ...
|
|
</programlisting>
|
|
If <literal>myaggregate</> is variadic, both these calls could be
|
|
perfectly valid.
|
|
</para>
|
|
|
|
<para>
|
|
For the same reason, it's wise to think twice before creating aggregate
|
|
functions with the same names and different numbers of regular arguments.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
A function written in C can detect that it is being called as an
|
|
aggregate transition or final function by calling
|
|
<function>AggCheckCallContext</>, for example:
|
|
<programlisting>
|
|
if (AggCheckCallContext(fcinfo, NULL))
|
|
</programlisting>
|
|
One reason for checking this is that when it is true for a transition
|
|
function, the first input
|
|
must be a temporary transition value and can therefore safely be modified
|
|
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.
|
|
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
|
|
final transition value.)
|
|
</para>
|
|
|
|
<para>
|
|
For further details see the
|
|
<xref linkend="sql-createaggregate">
|
|
command.
|
|
</para>
|
|
</sect1>
|