Skip to content

P
Postgres FD Implementation
Commit a1916daf authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Change cross reference to CREATE AGGREGATE to a citation, since the 

 Programmer's Guide does not have access to the reference page.
Normalize markup.
parent 835d78d5
Hide whitespace changes
Inline Side-by-side
Showing with 117 additions and 94 deletions
doc/src/sgml/xaggr.sgml
View file @ a1916daf
<Chapter Id="xaggr"> <chapter id="xaggr">
<Title>Extending <Acronym>SQL</Acronym>: Aggregates</Title> <title>Extending <acronym>SQL</acronym>: Aggregates</title>
<Para> <para>
Aggregate functions in <ProductName>Postgres</ProductName> Aggregate functions in <productname>Postgres</productname>
are expressed as <firstterm>state values</firstterm> are expressed as <firstterm>state values</firstterm>
and <firstterm>state transition functions</firstterm>. and <firstterm>state transition functions</firstterm>.
That is, an aggregate can be That is, an aggregate can be
defined in terms of state that is modified whenever an defined in terms of state that is modified whenever an
input item is processed. To define a new aggregate input item is processed. To define a new aggregate
function, one selects a datatype for the state value, function, one selects a datatype for the state value,
an initial value for the state, and a state transition an initial value for the state, and a state transition
function. The state transition function is just an function. The state transition function is just an
ordinary function that could also be used outside the ordinary function that could also be used outside the
context of the aggregate. context of the aggregate.
</Para> </para>
<Para> <para>
Actually, in order to make it easier to construct useful Actually, in order to make it easier to construct useful
aggregates from existing functions, an aggregate can have aggregates from existing functions, an aggregate can have
one or two separate state values, one or two transition one or two separate state values, one or two transition
functions to update those state values, and a functions to update those state values, and a
<firstterm>final function</firstterm> that computes the <firstterm>final function</firstterm> that computes the
actual aggregate result from the ending state values. actual aggregate result from the ending state values.
</Para> </para>
<Para> <para>
Thus there can be as many as four datatypes involved: Thus there can be as many as four datatypes involved:
the type of the input data items, the type of the aggregate's the type of the input data items, the type of the aggregate's
result, and the types of the two state values. Only the result, and the types of the two state values. Only the
input and result datatypes are seen by a user of the aggregate. input and result datatypes are seen by a user of the aggregate.
</Para> </para>
<Para> <para>
Some state transition functions need to look at each successive Some state transition functions need to look at each successive
input to compute the next state value, while others ignore the input to compute the next state value, while others ignore the
specific input value and simply update their internal state. specific input value and simply update their internal state.
(The most useful example of the second kind is a running count (The most useful example of the second kind is a running count
of the number of input items.) The <ProductName>Postgres</ProductName> of the number of input items.) The <productname>Postgres</productname>
aggregate machinery defines <Acronym>sfunc1</Acronym> for aggregate machinery defines <acronym>sfunc1</acronym> for
an aggregate as a function that is passed both the old state an aggregate as a function that is passed both the old state
value and the current input value, while <Acronym>sfunc2</Acronym> value and the current input value, while <acronym>sfunc2</acronym>
is a function that is passed only the old state value. is a function that is passed only the old state value.
</Para> </para>
<Para> <para>
If we define an aggregate that uses only <Acronym>sfunc1</Acronym>, If we define an aggregate that uses only <acronym>sfunc1</acronym>,
we have an aggregate that computes a running function of we have an aggregate that computes a running function of
the attribute values from each instance. "Sum" is an the attribute values from each instance. "Sum" is an
example of this kind of aggregate. "Sum" starts at example of this kind of aggregate. "Sum" starts at
zero and always adds the current instance's value to zero and always adds the current instance's value to
its running total. For example, if we want to make a Sum its running total. For example, if we want to make a Sum
aggregate to work on a datatype for complex numbers, aggregate to work on a datatype for complex numbers,
we only need the addition function for that datatype. we only need the addition function for that datatype.
The aggregate definition is: The aggregate definition is:
<ProgramListing> <programlisting>
CREATE AGGREGATE complex_sum ( CREATE AGGREGATE complex_sum (
sfunc1 = complex_add, sfunc1 = complex_add,
basetype = complex, basetype = complex,
...@@ -69,27 +69,27 @@ SELECT complex_sum(a) FROM test_complex; ...@@ -69,27 +69,27 @@ SELECT complex_sum(a) FROM test_complex;
+------------+ +------------+
|(34,53.9) | |(34,53.9) |
+------------+ +------------+
</ProgramListing> </programlisting>
(In practice, we'd just name the aggregate "sum", and rely on (In practice, we'd just name the aggregate "sum", and rely on
<ProductName>Postgres</ProductName> to figure out which kind <productname>Postgres</productname> to figure out which kind
of sum to apply to a complex column.) of sum to apply to a complex column.)
</Para> </para>
<Para> <para>
If we define only <Acronym>sfunc2</Acronym>, we are If we define only <acronym>sfunc2</acronym>, we are
specifying an aggregate specifying an aggregate
that computes a running function that is independent of that computes a running function that is independent of
the attribute values from each instance. the attribute values from each instance.
"Count" is the most common example of this kind of "Count" is the most common example of this kind of
aggregate. "Count" starts at zero and adds one to its aggregate. "Count" starts at zero and adds one to its
running total for each instance, ignoring the instance running total for each instance, ignoring the instance
value. Here, we use the built-in value. Here, we use the built-in
<Acronym>int4inc</Acronym> routine to do <acronym>int4inc</acronym> routine to do
the work for us. This routine increments (adds one to) the work for us. This routine increments (adds one to)
its argument. its argument.
<ProgramListing> <programlisting>
CREATE AGGREGATE my_count ( CREATE AGGREGATE my_count (
sfunc2 = int4inc, -- add one sfunc2 = int4inc, -- add one
basetype = int4, basetype = int4,
...@@ -104,21 +104,22 @@ SELECT my_count(*) as emp_count from EMP; ...@@ -104,21 +104,22 @@ SELECT my_count(*) as emp_count from EMP;
+----------+ +----------+
|5 | |5 |
+----------+ +----------+
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
"Average" is an example of an aggregate that requires "Average" is an example of an aggregate that requires
both a function to compute the running sum and a function both a function to compute the running sum and a function
to compute the running count. When all of the to compute the running count. When all of the
instances have been processed, the final answer for the instances have been processed, the final answer for the
aggregate is the running sum divided by the running aggregate is the running sum divided by the running
count. We use the <Acronym>int4pl</Acronym> and <Acronym>int4inc</Acronym> routines we used count. We use the <acronym>int4pl</acronym> and
before as well as the <ProductName>Postgres</ProductName> integer division <acronym>int4inc</acronym> routines we used
routine, <Acronym>int4div</Acronym>, to compute the division of the sum by before as well as the <productname>Postgres</productname> integer division
the count. routine, <acronym>int4div</acronym>, to compute the division of the sum by
the count.
<ProgramListing>
<programlisting>
CREATE AGGREGATE my_average ( CREATE AGGREGATE my_average (
sfunc1 = int4pl, -- sum sfunc1 = int4pl, -- sum
basetype = int4, basetype = int4,
...@@ -137,12 +138,34 @@ SELECT my_average(salary) as emp_average FROM EMP; ...@@ -137,12 +138,34 @@ SELECT my_average(salary) as emp_average FROM EMP;
+------------+ +------------+
|1640 | |1640 |
+------------+ +------------+
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
For further details see For further details see
<xref endterm="sql-createaggregate-title" <!--
linkend="sql-createaggregate-title">. Not available in the Programmer's Guide
</Para> <xref endterm="sql-createaggregate-title"
</Chapter> linkend="sql-createaggregate-title">.
-->
<command>CREATE AGGREGATE</command> in
<citetitle>The PostgreSQL User's Guide</citetitle>.
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment