2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/xaggr.sgml -->
|
2000-03-31 05:27:42 +02:00
|
|
|
|
2003-04-10 03:22:45 +02:00
|
|
|
<sect1 id="xaggr">
|
2011-02-01 23:00:26 +01:00
|
|
|
<title>User-defined Aggregates</title>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2001-05-13 00:51:36 +02:00
|
|
|
<indexterm zone="xaggr">
|
2003-08-31 19:32:24 +02:00
|
|
|
<primary>aggregate function</primary>
|
|
|
|
<secondary>user-defined</secondary>
|
2001-05-13 00:51:36 +02:00
|
|
|
</indexterm>
|
|
|
|
|
2000-03-30 07:07:48 +02:00
|
|
|
<para>
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
Aggregate functions in <productname>PostgreSQL</productname>
|
|
|
|
are defined in terms of <firstterm>state values</firstterm>
|
2000-03-30 07:07:48 +02:00
|
|
|
and <firstterm>state transition functions</firstterm>.
|
2006-07-27 21:52:07 +02:00
|
|
|
That is, an aggregate operates using a state value that is updated
|
|
|
|
as each successive input row is processed.
|
|
|
|
To define a new aggregate
|
2001-09-10 23:58:47 +02:00
|
|
|
function, one selects a data type for the state value,
|
2000-03-30 07:07:48 +02:00
|
|
|
an initial value for the state, and a state transition
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
function. The state transition function takes the previous state
|
|
|
|
value and the aggregate's input value(s) for the current row, and
|
|
|
|
returns a new state value.
|
|
|
|
A <firstterm>final function</firstterm>
|
2003-04-10 03:22:45 +02:00
|
|
|
can also be specified, in case the desired result of the aggregate
|
2000-07-17 05:05:41 +02:00
|
|
|
is different from the data that needs to be kept in the running
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
state value. The final function takes the last state value
|
|
|
|
and returns whatever is wanted as the aggregate result.
|
|
|
|
In principle, the transition and final functions are just ordinary
|
|
|
|
functions that could also be used outside the context of the
|
|
|
|
aggregate. (In practice, it's often helpful for performance reasons
|
|
|
|
to create specialized transition functions that can only work when
|
|
|
|
called as part of an aggregate.)
|
2000-03-30 07:07:48 +02:00
|
|
|
</para>
|
2000-03-26 21:45:21 +02:00
|
|
|
|
2000-03-30 07:07:48 +02:00
|
|
|
<para>
|
2003-04-10 03:22:45 +02:00
|
|
|
Thus, in addition to the argument and result data types seen by a user
|
2001-09-10 23:58:47 +02:00
|
|
|
of the aggregate, there is an internal state-value data type that
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
might be different from both the argument and result types.
|
2000-03-30 07:07:48 +02:00
|
|
|
</para>
|
2000-03-26 21:45:21 +02:00
|
|
|
|
2000-03-30 07:07:48 +02:00
|
|
|
<para>
|
2000-07-17 05:05:41 +02:00
|
|
|
If we define an aggregate that does not use a final function,
|
2000-03-30 07:07:48 +02:00
|
|
|
we have an aggregate that computes a running function of
|
2003-04-10 03:22:45 +02:00
|
|
|
the column values from each row. <function>sum</> is an
|
|
|
|
example of this kind of aggregate. <function>sum</> starts at
|
2001-01-14 00:58:55 +01:00
|
|
|
zero and always adds the current row's value to
|
2002-01-07 03:29:15 +01:00
|
|
|
its running total. For example, if we want to make a <function>sum</>
|
2001-09-10 23:58:47 +02:00
|
|
|
aggregate to work on a data type for complex numbers,
|
|
|
|
we only need the addition function for that data type.
|
2003-04-10 03:22:45 +02:00
|
|
|
The aggregate definition would be:
|
2008-11-20 22:10:44 +01:00
|
|
|
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
<programlisting>
|
2006-04-15 19:45:46 +02:00
|
|
|
CREATE AGGREGATE sum (complex)
|
|
|
|
(
|
2000-07-17 05:05:41 +02:00
|
|
|
sfunc = complex_add,
|
|
|
|
stype = complex,
|
|
|
|
initcond = '(0,0)'
|
1998-10-30 20:37:19 +01:00
|
|
|
);
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
which we might use like this:
|
1998-03-01 09:16:16 +01:00
|
|
|
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
<programlisting>
|
2006-04-15 19:45:46 +02:00
|
|
|
SELECT sum(a) FROM test_complex;
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2006-04-15 19:45:46 +02:00
|
|
|
sum
|
|
|
|
-----------
|
2002-01-07 03:29:15 +01:00
|
|
|
(34,53.9)
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
</programlisting>
|
2000-03-26 21:45:21 +02:00
|
|
|
|
2006-04-15 19:45:46 +02:00
|
|
|
(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>.)
|
2000-03-30 07:07:48 +02:00
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2000-03-30 07:07:48 +02:00
|
|
|
<para>
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
The above definition of <function>sum</function> will return zero
|
|
|
|
(the initial state value) if there are no nonnull input values.
|
2004-11-15 07:32:15 +01:00
|
|
|
Perhaps we want to return null in that case instead — the SQL standard
|
2002-01-07 03:29:15 +01:00
|
|
|
expects <function>sum</function> to behave that way. We can do this simply by
|
2001-09-10 23:58:47 +02:00
|
|
|
omitting the <literal>initcond</literal> phrase, so that the initial state
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
value is null. Ordinarily this would mean that the <literal>sfunc</literal>
|
|
|
|
would need to check for a null state-value input. But for
|
2003-08-10 00:50:22 +02:00
|
|
|
<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
|
2000-07-17 05:05:41 +02:00
|
|
|
the state variable and then start applying the transition function
|
2003-04-10 03:22:45 +02:00
|
|
|
at the second nonnull input value. <productname>PostgreSQL</productname>
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
will do that automatically if the initial state value is null and
|
2001-09-13 17:55:24 +02:00
|
|
|
the transition function is marked <quote>strict</> (i.e., not to be called
|
2003-04-10 03:22:45 +02:00
|
|
|
for null inputs).
|
2000-03-30 07:07:48 +02:00
|
|
|
</para>
|
2008-11-20 22:10:44 +01:00
|
|
|
|
2000-03-30 07:07:48 +02:00
|
|
|
<para>
|
2001-09-13 17:55:24 +02:00
|
|
|
Another bit of default behavior for a <quote>strict</> transition function
|
2000-07-17 05:05:41 +02:00
|
|
|
is that the previous state value is retained unchanged whenever a
|
2003-04-10 03:22:45 +02:00
|
|
|
null input value is encountered. Thus, null values are ignored. If you
|
2006-07-27 21:52:07 +02:00
|
|
|
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.
|
2000-07-17 05:05:41 +02:00
|
|
|
</para>
|
2008-11-20 22:10:44 +01:00
|
|
|
|
2000-07-17 05:05:41 +02:00
|
|
|
<para>
|
2006-07-27 21:52:07 +02:00
|
|
|
<function>avg</> (average) is a more complex example of an aggregate.
|
|
|
|
It requires
|
2000-07-17 05:05:41 +02:00
|
|
|
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
|
2011-03-23 21:56:55 +01:00
|
|
|
these quantities. Average is typically implemented by using an
|
|
|
|
array as the state value. For example,
|
2000-07-17 05:05:41 +02:00
|
|
|
the built-in implementation of <function>avg(float8)</function>
|
|
|
|
looks like:
|
|
|
|
|
2002-01-07 03:29:15 +01:00
|
|
|
<programlisting>
|
2006-04-15 19:45:46 +02:00
|
|
|
CREATE AGGREGATE avg (float8)
|
|
|
|
(
|
2000-07-17 05:05:41 +02:00
|
|
|
sfunc = float8_accum,
|
2000-10-23 02:46:07 +02:00
|
|
|
stype = float8[],
|
2000-07-17 05:05:41 +02:00
|
|
|
finalfunc = float8_avg,
|
2011-03-23 17:33:14 +01:00
|
|
|
initcond = '{0,0,0}'
|
1998-10-30 20:37:19 +01:00
|
|
|
);
|
2002-01-07 03:29:15 +01:00
|
|
|
</programlisting>
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
</para>
|
2011-03-23 21:56:55 +01:00
|
|
|
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
<function>float8_accum</> requires a three-element array, not just
|
2011-03-23 21:56:55 +01:00
|
|
|
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
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
some other aggregates besides <function>avg</>.
|
|
|
|
</para>
|
|
|
|
</note>
|
2000-03-26 21:45:21 +02:00
|
|
|
|
2014-04-12 17:58:53 +02:00
|
|
|
<para>
|
|
|
|
Aggregate function calls in SQL allow <literal>DISTINCT</>
|
|
|
|
and <literal>ORDER BY</> options that control which rows are fed
|
|
|
|
to the aggregate's transition function and in what order. These
|
|
|
|
options are implemented behind the scenes and are not the concern
|
|
|
|
of the aggregate's support functions.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For further details see the
|
|
|
|
<xref linkend="sql-createaggregate">
|
|
|
|
command.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2 id="xaggr-moving-aggregates">
|
|
|
|
<title>Moving-Aggregate Mode</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>moving-aggregate mode</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>aggregate function</primary>
|
|
|
|
<secondary>moving aggregate</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Aggregate functions can optionally support <firstterm>moving-aggregate
|
|
|
|
mode</>, which allows substantially faster execution of aggregate
|
|
|
|
functions within windows with moving frame starting points.
|
|
|
|
(See <xref linkend="tutorial-window">
|
|
|
|
and <xref linkend="syntax-window-functions"> for information about use of
|
|
|
|
aggregate functions as window functions.)
|
|
|
|
The basic idea is that in addition to a normal <quote>forward</>
|
|
|
|
transition function, the aggregate provides an <firstterm>inverse
|
|
|
|
transition function</>, which allows rows to be removed from the
|
|
|
|
aggregate's running state value when they exit the window frame.
|
|
|
|
For example a <function>sum</> aggregate, which uses addition as the
|
|
|
|
forward transition function, would use subtraction as the inverse
|
|
|
|
transition function. Without an inverse transition function, the window
|
|
|
|
function mechanism must recalculate the aggregate from scratch each time
|
|
|
|
the frame starting point moves, resulting in run time proportional to the
|
|
|
|
number of input rows times the average frame length. With an inverse
|
|
|
|
transition function, the run time is only proportional to the number of
|
|
|
|
input rows.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The inverse transition function is passed the current state value and the
|
|
|
|
aggregate input value(s) for the earliest row included in the current
|
|
|
|
state. It must reconstruct what the state value would have been if the
|
|
|
|
given input value had never been aggregated, but only the rows following
|
|
|
|
it. This sometimes requires that the forward transition function keep
|
|
|
|
more state than is needed for plain aggregation mode. Therefore, the
|
|
|
|
moving-aggregate mode uses a completely separate implementation from the
|
|
|
|
plain mode: it has its own state data type, its own forward transition
|
|
|
|
function, and its own final function if needed. These can be the same as
|
|
|
|
the plain mode's data type and functions, if there is no need for extra
|
|
|
|
state.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As an example, we could extend the <function>sum</> aggregate given above
|
|
|
|
to support moving-aggregate mode like this:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE AGGREGATE sum (complex)
|
|
|
|
(
|
|
|
|
sfunc = complex_add,
|
|
|
|
stype = complex,
|
|
|
|
initcond = '(0,0)',
|
|
|
|
msfunc = complex_add,
|
|
|
|
minvfunc = complex_sub,
|
|
|
|
mstype = complex,
|
|
|
|
minitcond = '(0,0)'
|
|
|
|
);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
The parameters whose names begin with <literal>m</> define the
|
|
|
|
moving-aggregate implementation. Except for the inverse transition
|
|
|
|
function <literal>minvfunc</>, they correspond to the plain-aggregate
|
|
|
|
parameters without <literal>m</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The forward transition function for moving-aggregate mode is not allowed
|
|
|
|
to return NULL as the new state value. If the inverse transition
|
|
|
|
function returns NULL, this is taken as an indication that the inverse
|
|
|
|
function cannot reverse the state calculation for this particular input,
|
|
|
|
and so the aggregate calculation will be redone from scratch for the
|
|
|
|
current frame starting position. This convention allows moving-aggregate
|
|
|
|
mode to be used in situations where there are some infrequent cases that
|
|
|
|
are impractical to reverse out of the running state value. The inverse
|
|
|
|
transition function can <quote>punt</> on these cases, and yet still come
|
|
|
|
out ahead so long as it can work for most cases. As an example, an
|
|
|
|
aggregate working with floating-point numbers might choose to punt when
|
|
|
|
a <literal>NaN</> (not a number) input has to be removed from the running
|
|
|
|
state value.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When writing moving-aggregate support functions, it is important to be
|
|
|
|
sure that the inverse transition function can reconstruct the correct
|
|
|
|
state value exactly. Otherwise there might be user-visible differences
|
|
|
|
in results depending on whether the moving-aggregate mode is used.
|
|
|
|
An example of an aggregate for which adding an inverse transition
|
|
|
|
function seems easy at first, yet where this requirement cannot be met
|
|
|
|
is <function>sum</> over <type>float4</> or <type>float8</> inputs. A
|
|
|
|
naive declaration of <function>sum(<type>float8</>)</function> could be
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE AGGREGATE unsafe_sum (float8)
|
|
|
|
(
|
|
|
|
stype = float8,
|
|
|
|
sfunc = float8pl,
|
|
|
|
mstype = float8,
|
|
|
|
msfunc = float8pl,
|
|
|
|
minvfunc = float8mi
|
|
|
|
);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
This aggregate, however, can give wildly different results than it would
|
|
|
|
have without the inverse transition function. For example, consider
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT
|
|
|
|
unsafe_sum(x) OVER (ORDER BY n ROWS BETWEEN CURRENT ROW AND 1 FOLLOWING)
|
|
|
|
FROM (VALUES (1, 1.0e20::float8),
|
|
|
|
(2, 1.0::float8)) AS v (n,x);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
This query returns <literal>0</> as its second result, rather than the
|
|
|
|
expected answer of <literal>1</>. The cause is the limited precision of
|
|
|
|
floating-point values: adding <literal>1</> to <literal>1e20</> results
|
|
|
|
in <literal>1e20</> again, and so subtracting <literal>1e20</> from that
|
|
|
|
yields <literal>0</>, not <literal>1</>. Note that this is a limitation
|
|
|
|
of floating-point arithmetic in general, not a limitation
|
|
|
|
of <productname>PostgreSQL</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="xaggr-polymorphic-aggregates">
|
|
|
|
<title>Polymorphic and Variadic Aggregates</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>aggregate function</primary>
|
|
|
|
<secondary>polymorphic</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>aggregate function</primary>
|
|
|
|
<secondary>variadic</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
2000-03-30 07:07:48 +02:00
|
|
|
<para>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
Aggregate functions can use polymorphic
|
2003-08-10 00:50:22 +02:00
|
|
|
state transition functions or final functions, so that the same functions
|
|
|
|
can be used to implement multiple aggregates.
|
2003-08-31 19:32:24 +02:00
|
|
|
See <xref linkend="extend-types-polymorphic">
|
2003-08-10 00:50:22 +02:00
|
|
|
for an explanation of polymorphic functions.
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
Going a step further, the aggregate function itself can be specified
|
2006-07-27 21:52:07 +02:00
|
|
|
with polymorphic input type(s) and state type, allowing a single
|
2003-08-10 00:50:22 +02:00
|
|
|
aggregate definition to serve for multiple input data types.
|
|
|
|
Here is an example of a polymorphic aggregate:
|
|
|
|
|
|
|
|
<programlisting>
|
2006-04-15 19:45:46 +02:00
|
|
|
CREATE AGGREGATE array_accum (anyelement)
|
|
|
|
(
|
2003-08-10 00:50:22 +02:00
|
|
|
sfunc = array_append,
|
|
|
|
stype = anyarray,
|
|
|
|
initcond = '{}'
|
|
|
|
);
|
|
|
|
</programlisting>
|
|
|
|
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
Here, the actual state type for any given aggregate call is the array type
|
2008-11-20 22:10:44 +01:00
|
|
|
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.)
|
2003-08-10 00:50:22 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here's the output using two different actual data types as arguments:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT attrelid::regclass, array_accum(attname)
|
2003-11-12 23:47:47 +01:00
|
|
|
FROM pg_attribute
|
2005-08-15 04:40:36 +02:00
|
|
|
WHERE attnum > 0 AND attrelid = 'pg_tablespace'::regclass
|
2003-11-12 23:47:47 +01:00
|
|
|
GROUP BY attrelid;
|
|
|
|
|
2005-08-15 04:40:36 +02:00
|
|
|
attrelid | array_accum
|
|
|
|
---------------+---------------------------------------
|
2011-12-07 10:35:00 +01:00
|
|
|
pg_tablespace | {spcname,spcowner,spcacl,spcoptions}
|
2003-08-10 00:50:22 +02:00
|
|
|
(1 row)
|
|
|
|
|
2008-11-20 22:10:44 +01:00
|
|
|
SELECT attrelid::regclass, array_accum(atttypid::regtype)
|
2003-11-12 23:47:47 +01:00
|
|
|
FROM pg_attribute
|
2005-08-15 04:40:36 +02:00
|
|
|
WHERE attnum > 0 AND attrelid = 'pg_tablespace'::regclass
|
2003-11-12 23:47:47 +01:00
|
|
|
GROUP BY attrelid;
|
|
|
|
|
2008-11-20 22:10:44 +01:00
|
|
|
attrelid | array_accum
|
|
|
|
---------------+---------------------------
|
2011-12-07 10:35:00 +01:00
|
|
|
pg_tablespace | {name,oid,aclitem[],text[]}
|
2003-08-10 00:50:22 +02:00
|
|
|
(1 row)
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
Allow aggregate functions to be VARIADIC.
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.
2013-09-03 23:08:38 +02:00
|
|
|
<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
|
2014-04-12 17:58:53 +02:00
|
|
|
function(s) must have the same array type as their last argument. The
|
|
|
|
transition function(s) typically would also be marked <literal>VARIADIC</>,
|
Allow aggregate functions to be VARIADIC.
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.
2013-09-03 23:08:38 +02:00
|
|
|
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>
|
|
|
|
|
2014-04-12 17:58:53 +02:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="xaggr-ordered-set-aggregates">
|
|
|
|
<title>Ordered-Set Aggregates</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>aggregate function</primary>
|
|
|
|
<secondary>ordered set</secondary>
|
|
|
|
</indexterm>
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
The aggregates we have been describing so far are <quote>normal</>
|
|
|
|
aggregates. <productname>PostgreSQL</> also
|
|
|
|
supports <firstterm>ordered-set aggregates</>, which differ from
|
|
|
|
normal aggregates in two key ways. First, in addition to ordinary
|
|
|
|
aggregated arguments that are evaluated once per input row, an
|
|
|
|
ordered-set aggregate can have <quote>direct</> arguments that are
|
|
|
|
evaluated only once per aggregation operation. Second, the syntax
|
|
|
|
for the ordinary aggregated arguments specifies a sort ordering
|
|
|
|
for them explicitly. An ordered-set aggregate is usually
|
|
|
|
used to implement a computation that depends on a specific row
|
|
|
|
ordering, for instance rank or percentile, so that the sort ordering
|
|
|
|
is a required aspect of any call. For example, the built-in
|
|
|
|
definition of <function>percentile_disc</> is equivalent to:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE AGGREGATE percentile_disc (float8 ORDER BY anyelement)
|
|
|
|
(
|
|
|
|
sfunc = ordered_set_transition,
|
|
|
|
stype = internal,
|
|
|
|
finalfunc = percentile_disc_final
|
|
|
|
);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
which could be used to obtain a median household income like this:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY income) FROM households;
|
|
|
|
percentile_disc
|
|
|
|
-----------------
|
|
|
|
50489
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
Here, <literal>0.5</> is a direct argument; it would make no sense
|
|
|
|
for the percentile fraction to be a value varying across rows.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Unlike the case for normal aggregates, the sorting of input rows for
|
|
|
|
an ordered-set aggregate is <emphasis>not</> done behind the scenes,
|
|
|
|
but is the responsibility of the aggregate's support functions.
|
|
|
|
The typical implementation approach is to keep a reference to
|
|
|
|
a <quote>tuplesort</> object in the aggregate's state value, feed the
|
|
|
|
incoming rows into that object, and then complete the sorting and
|
|
|
|
read out the data in the final function. This design allows the
|
|
|
|
final function to perform special operations such as injecting
|
|
|
|
additional <quote>hypothetical</> rows into the data to be sorted.
|
|
|
|
While normal aggregates can often be implemented with support
|
|
|
|
functions written in <application>PL/pgSQL</application> or another
|
|
|
|
PL language, ordered-set aggregates generally have to be written in
|
|
|
|
C, since their state values aren't definable as any SQL datatype.
|
|
|
|
(In the above example, notice that the state value is declared as
|
|
|
|
type <type>internal</> — this is typical.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The state transition function for an ordered-set aggregate receives
|
|
|
|
the current state value plus the aggregated input values for
|
|
|
|
each row, and returns the updated state value. This is the
|
|
|
|
same definition as for normal aggregates, but note that the direct
|
|
|
|
arguments (if any) are not provided. The final function receives
|
|
|
|
the last state value, the values of the direct arguments if any,
|
|
|
|
and null values corresponding to the aggregated input(s). While the
|
|
|
|
null values seem useless at first sight, they are important because
|
|
|
|
they make it possible to include the data types of the aggregated
|
|
|
|
input(s) in the final function's signature, which may be necessary
|
|
|
|
to resolve the output type of a polymorphic aggregate. For example,
|
|
|
|
the built-in <function>mode()</> ordered-set aggregate takes a
|
|
|
|
single aggregated column of any sortable data type and returns a
|
|
|
|
value of that same type. This is possible because the final function
|
|
|
|
is declared as <literal>mode_final(internal, anyelement) returns
|
|
|
|
anyelement</>, with the <type>anyelement</> parameter corresponding
|
|
|
|
to the dummy null argument that represents the aggregated column.
|
|
|
|
The actual data is conveyed in the <type>internal</>-type state
|
|
|
|
value, but type resolution needs a parse-time indication of what the
|
|
|
|
result data type will be, and the dummy argument provides that.
|
|
|
|
In the example of <function>percentile_disc</>, the support functions
|
|
|
|
are respectively declared as
|
|
|
|
<literal>ordered_set_transition(internal, "any") returns internal</>
|
|
|
|
and <literal>percentile_disc_final(internal, float8, anyelement)
|
|
|
|
returns anyelement</>.
|
|
|
|
</para>
|
|
|
|
|
2014-04-12 17:58:53 +02:00
|
|
|
<para>
|
|
|
|
Currently, ordered-set aggregates cannot be used as window functions,
|
|
|
|
and therefore there is no need for them to support moving-aggregate mode.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="xaggr-support-functions">
|
|
|
|
<title>Support Functions for Aggregates</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>aggregate function</primary>
|
|
|
|
<secondary>support functions for</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
2005-03-12 21:25:06 +01:00
|
|
|
<para>
|
|
|
|
A function written in C can detect that it is being called as an
|
2010-02-08 21:39:52 +01:00
|
|
|
aggregate transition or final function by calling
|
|
|
|
<function>AggCheckCallContext</>, for example:
|
2005-03-12 21:25:06 +01:00
|
|
|
<programlisting>
|
2010-07-29 21:34:41 +02:00
|
|
|
if (AggCheckCallContext(fcinfo, NULL))
|
2005-03-12 21:25:06 +01:00
|
|
|
</programlisting>
|
2009-06-20 20:45:28 +02:00
|
|
|
One reason for checking this is that when it is true for a transition
|
|
|
|
function, the first input
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
must be a temporary state value and can therefore safely be modified
|
2011-03-23 21:56:55 +01:00
|
|
|
in-place rather than allocating a new copy.
|
|
|
|
See <literal>int8inc()</> for an example.
|
|
|
|
(This is the <emphasis>only</>
|
2009-06-20 20:45:28 +02:00
|
|
|
case where it is safe for a function to modify a pass-by-reference input.
|
Support ordered-set (WITHIN GROUP) aggregates.
This patch introduces generic support for ordered-set and hypothetical-set
aggregate functions, as well as implementations of the instances defined in
SQL:2008 (percentile_cont(), percentile_disc(), rank(), dense_rank(),
percent_rank(), cume_dist()). We also added mode() though it is not in the
spec, as well as versions of percentile_cont() and percentile_disc() that
can compute multiple percentile values in one pass over the data.
Unlike the original submission, this patch puts full control of the sorting
process in the hands of the aggregate's support functions. To allow the
support functions to find out how they're supposed to sort, a new API
function AggGetAggref() is added to nodeAgg.c. This allows retrieval of
the aggregate call's Aggref node, which may have other uses beyond the
immediate need. There is also support for ordered-set aggregates to
install cleanup callback functions, so that they can be sure that
infrastructure such as tuplesort objects gets cleaned up.
In passing, make some fixes in the recently-added support for variadic
aggregates, and make some editorial adjustments in the recent FILTER
additions for aggregates. Also, simplify use of IsBinaryCoercible() by
allowing it to succeed whenever the target type is ANY or ANYELEMENT.
It was inconsistent that it dealt with other polymorphic target types
but not these.
Atri Sharma and Andrew Gierth; reviewed by Pavel Stehule and Vik Fearing,
and rather heavily editorialized upon by Tom Lane
2013-12-23 22:11:35 +01:00
|
|
|
In particular, final functions for normal aggregates must not
|
|
|
|
modify their inputs in any case, because in some cases they will be
|
|
|
|
re-executed on the same final state value.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Another support routine available to aggregate functions written in C
|
|
|
|
is <function>AggGetAggref</>, which returns the <literal>Aggref</>
|
|
|
|
parse node that defines the aggregate call. This is mainly useful
|
|
|
|
for ordered-set aggregates, which can inspect the substructure of
|
|
|
|
the <literal>Aggref</> node to find out what sort ordering they are
|
|
|
|
supposed to implement. Examples can be found
|
|
|
|
in <filename>orderedsetaggs.c</> in the <productname>PostgreSQL</>
|
|
|
|
source code.
|
2005-03-12 21:25:06 +01:00
|
|
|
</para>
|
|
|
|
|
2014-04-12 17:58:53 +02:00
|
|
|
</sect2>
|
|
|
|
|
2003-04-10 03:22:45 +02:00
|
|
|
</sect1>
|