592 lines
25 KiB
Plaintext
592 lines
25 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/create_aggregate.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="SQL-CREATEAGGREGATE">
|
|
<indexterm zone="sql-createaggregate">
|
|
<primary>CREATE AGGREGATE</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle>CREATE AGGREGATE</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>CREATE AGGREGATE</refname>
|
|
<refpurpose>define a new aggregate function</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
CREATE AGGREGATE <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">arg_data_type</replaceable> [ , ... ] ) (
|
|
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
|
|
STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
|
|
[ , SSPACE = <replaceable class="PARAMETER">state_data_size</replaceable> ]
|
|
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
|
|
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
|
|
[ , MSFUNC = <replaceable class="PARAMETER">msfunc</replaceable> ]
|
|
[ , MINVFUNC = <replaceable class="PARAMETER">minvfunc</replaceable> ]
|
|
[ , MSTYPE = <replaceable class="PARAMETER">mstate_data_type</replaceable> ]
|
|
[ , MSSPACE = <replaceable class="PARAMETER">mstate_data_size</replaceable> ]
|
|
[ , MFINALFUNC = <replaceable class="PARAMETER">mffunc</replaceable> ]
|
|
[ , MINITCOND = <replaceable class="PARAMETER">minitial_condition</replaceable> ]
|
|
[ , SORTOP = <replaceable class="PARAMETER">sort_operator</replaceable> ]
|
|
)
|
|
|
|
CREATE AGGREGATE <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">arg_data_type</replaceable> [ , ... ] ]
|
|
ORDER BY [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">arg_data_type</replaceable> [ , ... ] ) (
|
|
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
|
|
STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
|
|
[ , SSPACE = <replaceable class="PARAMETER">state_data_size</replaceable> ]
|
|
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
|
|
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
|
|
[ , HYPOTHETICAL ]
|
|
)
|
|
|
|
<phrase>or the old syntax</phrase>
|
|
|
|
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
|
|
BASETYPE = <replaceable class="PARAMETER">base_type</replaceable>,
|
|
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
|
|
STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
|
|
[ , SSPACE = <replaceable class="PARAMETER">state_data_size</replaceable> ]
|
|
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
|
|
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
|
|
[ , MSFUNC = <replaceable class="PARAMETER">sfunc</replaceable> ]
|
|
[ , MINVFUNC = <replaceable class="PARAMETER">invfunc</replaceable> ]
|
|
[ , MSTYPE = <replaceable class="PARAMETER">state_data_type</replaceable> ]
|
|
[ , MSSPACE = <replaceable class="PARAMETER">state_data_size</replaceable> ]
|
|
[ , MFINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
|
|
[ , MINITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
|
|
[ , SORTOP = <replaceable class="PARAMETER">sort_operator</replaceable> ]
|
|
)
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>CREATE AGGREGATE</command> defines a new aggregate
|
|
function. Some basic and commonly-used aggregate functions are
|
|
included with the distribution; they are documented in <xref
|
|
linkend="functions-aggregate">. If one defines new types or needs
|
|
an aggregate function not already provided, then <command>CREATE
|
|
AGGREGATE</command> can be used to provide the desired features.
|
|
</para>
|
|
|
|
<para>
|
|
If a schema name is given (for example, <literal>CREATE AGGREGATE
|
|
myschema.myagg ...</>) then the aggregate function is created in the
|
|
specified schema. Otherwise it is created in the current schema.
|
|
</para>
|
|
|
|
<para>
|
|
An aggregate function is identified by its name and input data type(s).
|
|
Two aggregates in the same schema can have the same name if they operate on
|
|
different input types. The
|
|
name and input data type(s) of an aggregate must also be distinct from
|
|
the name and input data type(s) of every ordinary function in the same
|
|
schema.
|
|
This behavior is identical to overloading of ordinary function names
|
|
(see <xref linkend="sql-createfunction">).
|
|
</para>
|
|
|
|
<para>
|
|
A simple aggregate function is made from one or two ordinary
|
|
functions:
|
|
a state transition function
|
|
<replaceable class="PARAMETER">sfunc</replaceable>,
|
|
and an optional final calculation function
|
|
<replaceable class="PARAMETER">ffunc</replaceable>.
|
|
These are used as follows:
|
|
<programlisting>
|
|
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-values ) ---> next-internal-state
|
|
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> creates a temporary variable
|
|
of data type <replaceable class="PARAMETER">stype</replaceable>
|
|
to hold the current internal state of the aggregate. At each input row,
|
|
the aggregate argument value(s) are calculated and
|
|
the state transition function is invoked with the current state value
|
|
and the new argument value(s) to calculate a new
|
|
internal state value. After all the rows have been processed,
|
|
the final function is invoked once to calculate the aggregate's return
|
|
value. If there is no final function then the ending state value
|
|
is returned as-is.
|
|
</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
|
|
<type>text</type>, but it must be a valid external representation
|
|
of a constant of the state value data type. If it is not supplied
|
|
then the state value starts out null.
|
|
</para>
|
|
|
|
<para>
|
|
If the state transition function is declared <quote>strict</quote>,
|
|
then it cannot be called with null inputs. With such a transition
|
|
function, aggregate execution behaves as follows. Rows with any null input
|
|
values are ignored (the function is not called and the previous state value
|
|
is retained). If the initial state value is null, then at the first row
|
|
with all-nonnull input values, the first argument value replaces the state
|
|
value, and the transition function is invoked at each subsequent row with
|
|
all-nonnull input values.
|
|
This is handy for implementing aggregates like <function>max</function>.
|
|
Note that this behavior is only available when
|
|
<replaceable class="PARAMETER">state_data_type</replaceable>
|
|
is the same as the first
|
|
<replaceable class="PARAMETER">arg_data_type</replaceable>.
|
|
When these types are different, you must supply a nonnull initial
|
|
condition or use a nonstrict transition function.
|
|
</para>
|
|
|
|
<para>
|
|
If the state transition function is not strict, then it will be called
|
|
unconditionally at each input row, and must deal with null inputs
|
|
and null state values for itself. This allows the aggregate
|
|
author to have full control over the aggregate's handling of null values.
|
|
</para>
|
|
|
|
<para>
|
|
If the final function is declared <quote>strict</quote>, then it will not
|
|
be called when the ending state value is null; instead a null result
|
|
will be returned automatically. (Of course this is just the normal
|
|
behavior of strict functions.) In any case the final function has
|
|
the option of returning a null value. For example, the final function for
|
|
<function>avg</function> returns null when it sees there were zero
|
|
input rows.
|
|
</para>
|
|
|
|
<para>
|
|
An aggregate can optionally support <firstterm>moving-aggregate mode</>,
|
|
as described in <xref linkend="xaggr-moving-aggregates">. This requires
|
|
specifying the <literal>MSFUNC</>, <literal>MINVFUNC</>,
|
|
and <literal>MSTYPE</> parameters, and optionally
|
|
the <literal>MSPACE</>, <literal>MFINALFUNC</>,
|
|
and <literal>MINITCOND</> parameters. Except for <literal>MINVFUNC</>,
|
|
these parameters work like the corresponding simple-aggregate parameters
|
|
without <literal>M</>; they define a separate implementation of the
|
|
aggregate that includes an inverse transition function.
|
|
</para>
|
|
|
|
<para>
|
|
The syntax with <literal>ORDER BY</literal> in the parameter list creates
|
|
a special type of aggregate called an <firstterm>ordered-set
|
|
aggregate</firstterm>; or if <literal>HYPOTHETICAL</> is specified, then
|
|
a <firstterm>hypothetical-set aggregate</firstterm> is created. These
|
|
aggregates operate over groups of sorted values in order-dependent ways,
|
|
so that specification of an input sort order is an essential part of a
|
|
call. Also, they can have <firstterm>direct</> arguments, which are
|
|
arguments that are evaluated only once per aggregation rather than once
|
|
per input row. Hypothetical-set aggregates are a subclass of ordered-set
|
|
aggregates in which some of the direct arguments are required to match,
|
|
in number and datatypes, the aggregated argument columns. This allows
|
|
the values of those direct arguments to be added to the collection of
|
|
aggregate-input rows as an additional <quote>hypothetical</> row.
|
|
</para>
|
|
|
|
<para>
|
|
Aggregates that behave like <function>MIN</> or <function>MAX</> can
|
|
sometimes be optimized by looking into an index instead of scanning every
|
|
input row. If this aggregate can be so optimized, indicate it by
|
|
specifying a <firstterm>sort operator</>. The basic requirement is that
|
|
the aggregate must yield the first element in the sort ordering induced by
|
|
the operator; in other words:
|
|
<programlisting>
|
|
SELECT agg(col) FROM tab;
|
|
</programlisting>
|
|
must be equivalent to:
|
|
<programlisting>
|
|
SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
|
|
</programlisting>
|
|
Further assumptions are that the aggregate ignores null inputs, and that
|
|
it delivers a null result if and only if there were no non-null inputs.
|
|
Ordinarily, a data type's <literal><</> operator is the proper sort
|
|
operator for <function>MIN</>, and <literal>></> is the proper sort
|
|
operator for <function>MAX</>. Note that the optimization will never
|
|
actually take effect unless the specified operator is the <quote>less
|
|
than</quote> or <quote>greater than</quote> strategy member of a B-tree
|
|
index operator class.
|
|
</para>
|
|
|
|
<para>
|
|
To be able to create an aggregate function, you must
|
|
have <literal>USAGE</literal> privilege on the argument types, the state
|
|
type(s), and the return type, as well as <literal>EXECUTE</literal>
|
|
privilege on the transition and final functions.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name (optionally schema-qualified) of the aggregate function
|
|
to create.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">argmode</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
The mode of an argument: <literal>IN</> or <literal>VARIADIC</>.
|
|
(Aggregate functions do not support <literal>OUT</> arguments.)
|
|
If omitted, the default is <literal>IN</>. Only the last argument
|
|
can be marked <literal>VARIADIC</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">argname</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
The name of an argument. This is currently only useful for
|
|
documentation purposes. If omitted, the argument has no name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">arg_data_type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
An input data type on which this aggregate function operates.
|
|
To create a zero-argument aggregate function, write <literal>*</>
|
|
in place of the list of argument specifications. (An example of such an
|
|
aggregate is <function>count(*)</function>.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">base_type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
In the old syntax for <command>CREATE AGGREGATE</>, the input data type
|
|
is specified by a <literal>basetype</> parameter rather than being
|
|
written next to the aggregate name. Note that this syntax allows
|
|
only one input parameter. To define a zero-argument aggregate function
|
|
with this syntax, specify the <literal>basetype</> as
|
|
<literal>"ANY"</> (not <literal>*</>).
|
|
Ordered-set aggregates cannot be defined with the old syntax.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">sfunc</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the state transition function to be called for each
|
|
input row. For a normal <replaceable class="PARAMETER">N</>-argument
|
|
aggregate function, the <replaceable class="PARAMETER">sfunc</>
|
|
must take <replaceable class="PARAMETER">N</>+1 arguments,
|
|
the first being of type <replaceable
|
|
class="PARAMETER">state_data_type</replaceable> and the rest
|
|
matching the declared input data type(s) of the aggregate.
|
|
The function must return a value of type <replaceable
|
|
class="PARAMETER">state_data_type</replaceable>. This function
|
|
takes the current state value and the current input data value(s),
|
|
and returns the next state value.
|
|
</para>
|
|
|
|
<para>
|
|
For ordered-set (including hypothetical-set) aggregates, the state
|
|
transition function receives only the current state value and the
|
|
aggregated arguments, not the direct arguments. Otherwise it is the
|
|
same.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">state_data_type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The data type for the aggregate's state value.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">state_data_size</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The approximate average size (in bytes) of the aggregate's state value.
|
|
If this parameter is omitted or is zero, a default estimate is used
|
|
based on the <replaceable>state_data_type</>.
|
|
The planner uses this value to estimate the memory required for a
|
|
grouped aggregate query. The planner will consider using hash
|
|
aggregation for such a query only if the hash table is estimated to fit
|
|
in <xref linkend="guc-work-mem">; therefore, large values of this
|
|
parameter discourage use of hash aggregation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">ffunc</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the final function called to compute the aggregate's
|
|
result after all input rows have been traversed.
|
|
For a normal aggregate, this function
|
|
must take a single argument of type <replaceable
|
|
class="PARAMETER">state_data_type</replaceable>. The return
|
|
data type of the aggregate is defined as the return type of this
|
|
function. If <replaceable class="PARAMETER">ffunc</replaceable>
|
|
is not specified, then the ending state value is used as the
|
|
aggregate's result, and the return type is <replaceable
|
|
class="PARAMETER">state_data_type</replaceable>.
|
|
</para>
|
|
|
|
<para>
|
|
For ordered-set (including hypothetical-set) aggregates, the
|
|
final function receives not only the final state value,
|
|
but also the values of all the direct arguments, followed by
|
|
null values corresponding to each aggregated argument.
|
|
(The reason for including the aggregated arguments in the function
|
|
signature is that this may be necessary to allow correct resolution
|
|
of the aggregate result type, when a polymorphic aggregate is
|
|
being defined.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The initial setting for the state value. This must be a string
|
|
constant in the form accepted for the data type <replaceable
|
|
class="PARAMETER">state_data_type</replaceable>. If not
|
|
specified, the state value starts out null.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">msfunc</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the forward state transition function to be called for each
|
|
input row in moving-aggregate mode. This is exactly like the regular
|
|
transition function, except that its first argument and result are of
|
|
type <replaceable>mstate_data_type</>, which might be different
|
|
from <replaceable>state_data_type</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">minvfunc</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the inverse state transition function to be used in
|
|
moving-aggregate mode. This function has the same argument and
|
|
result types as <replaceable>msfunc</>, but it is used to remove
|
|
a value from the current aggregate state, rather than add a value to
|
|
it. The inverse transition function must have the same strictness
|
|
attribute as the forward state transition function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">mstate_data_type</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The data type for the aggregate's state value, when using
|
|
moving-aggregate mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">mstate_data_size</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The approximate average size (in bytes) of the aggregate's state
|
|
value, when using moving-aggregate mode. This works the same as
|
|
<replaceable>state_data_size</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">mffunc</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the final function called to compute the aggregate's
|
|
result after all input rows have been traversed, when using
|
|
moving-aggregate mode. This works the same as <replaceable>ffunc</>,
|
|
except that its input type is <replaceable>mstate_data_type</>.
|
|
The aggregate result type determined by <replaceable>mffunc</>
|
|
and <replaceable>mstate_data_type</> must match that determined by the
|
|
aggregate's regular implementation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">minitial_condition</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The initial setting for the state value, when using moving-aggregate
|
|
mode. This works the same as <replaceable>initial_condition</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="PARAMETER">sort_operator</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The associated sort operator for a <function>MIN</>- or
|
|
<function>MAX</>-like aggregate.
|
|
This is just an operator name (possibly schema-qualified).
|
|
The operator is assumed to have the same input data types as
|
|
the aggregate (which must be a single-argument normal aggregate).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>HYPOTHETICAL</literal></term>
|
|
<listitem>
|
|
<para>
|
|
For ordered-set aggregates only, this flag specifies that the aggregate
|
|
arguments are to be processed according to the requirements for
|
|
hypothetical-set aggregates: that is, the last few direct arguments must
|
|
match the data types of the aggregated (<literal>WITHIN GROUP</>)
|
|
arguments. The <literal>HYPOTHETICAL</literal> flag has no effect on
|
|
run-time behavior, only on parse-time resolution of the data types and
|
|
collations of the aggregate's arguments.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The parameters of <command>CREATE AGGREGATE</command> can be
|
|
written in any order, not just the order illustrated above.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
If an aggregate supports moving-aggregate mode, it will improve
|
|
calculation efficiency when the aggregate is used as a window function
|
|
for a window with moving frame start (that is, a frame start mode other
|
|
than <literal>UNBOUNDED PRECEDING</>). Conceptually, the forward
|
|
transition function adds input values to the aggregate's state when
|
|
they enter the window frame from the bottom, and the inverse transition
|
|
function removes them again when they leave the frame at the top. So,
|
|
when values are removed, they are always removed in the same order they
|
|
were added. Whenever the inverse transition function is invoked, it will
|
|
thus receive the earliest added but not yet removed argument value(s).
|
|
The inverse transition function can assume that at least one row will
|
|
remain in the current state after it removes the oldest row. (When this
|
|
would not be the case, the window function mechanism simply starts a
|
|
fresh aggregation, rather than using the inverse transition function.)
|
|
</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.
|
|
</para>
|
|
|
|
<para>
|
|
If no moving-aggregate implementation is supplied,
|
|
the aggregate can still be used with moving frames,
|
|
but <productname>PostgreSQL</productname> will recompute the whole
|
|
aggregation whenever the start of the frame moves.
|
|
Note that whether or not the aggregate supports moving-aggregate
|
|
mode, <productname>PostgreSQL</productname> can handle a moving frame
|
|
end without recalculation; this is done by continuing to add new values
|
|
to the aggregate's state. It is assumed that the final function does
|
|
not damage the aggregate's state value, so that the aggregation can be
|
|
continued even after an aggregate result value has been obtained for
|
|
one set of frame boundaries.
|
|
</para>
|
|
|
|
<para>
|
|
The syntax for ordered-set aggregates allows <literal>VARIADIC</>
|
|
to be specified for both the last direct parameter and the last
|
|
aggregated (<literal>WITHIN GROUP</>) parameter. However, the
|
|
current implementation restricts use of <literal>VARIADIC</>
|
|
in two ways. First, ordered-set aggregates can only use
|
|
<literal>VARIADIC "any"</>, not other variadic array types.
|
|
Second, if the last direct parameter is <literal>VARIADIC "any"</>,
|
|
then there can be only one aggregated parameter and it must also
|
|
be <literal>VARIADIC "any"</>. (In the representation used in the
|
|
system catalogs, these two parameters are merged into a single
|
|
<literal>VARIADIC "any"</> item, since <structname>pg_proc</> cannot
|
|
represent functions with more than one <literal>VARIADIC</> parameter.)
|
|
If the aggregate is a hypothetical-set aggregate, the direct arguments
|
|
that match the <literal>VARIADIC "any"</> parameter are the hypothetical
|
|
ones; any preceding parameters represent additional direct arguments
|
|
that are not constrained to match the aggregated arguments.
|
|
</para>
|
|
|
|
<para>
|
|
Currently, ordered-set aggregates do not need to support
|
|
moving-aggregate mode, since they cannot be used as window functions.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
See <xref linkend="xaggr">.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>CREATE AGGREGATE</command> is a
|
|
<productname>PostgreSQL</productname> language extension. The SQL
|
|
standard does not provide for user-defined aggregate functions.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="sql-alteraggregate"></member>
|
|
<member><xref linkend="sql-dropaggregate"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|