discuss how to retrieve the data out of the database.
discuss how to retrieve the data out of the database.
</para>
</para>
<sect1 id="queries-overview">
<sect1 id="queries-overview">
<title>Overview</title>
<title>Overview</title>
...
@@ -21,14 +22,18 @@
...
@@ -21,14 +22,18 @@
SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable> <optional><replaceable>sort_specification</replaceable></optional>
SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable> <optional><replaceable>sort_specification</replaceable></optional>
</synopsis>
</synopsis>
The following sections describe the details of the select list, the
The following sections describe the details of the select list, the
table expression, and the sort specification. The simplest kind of
table expression, and the sort specification.
query has the form
</para>
<para>
The simplest kind of query has the form
<programlisting>
<programlisting>
SELECT * FROM table1;
SELECT * FROM table1;
</programlisting>
</programlisting>
Assuming that there is a table called table1, this command would
Assuming that there is a table called <literal>table1</literal>,
retrieve all rows and all columns from table1. (The method of
this command would retrieve all rows and all columns from
retrieval depends on the client application. For example, the
<literal>table1</literal>. (The method of retrieval depends on the
client application. For example, the
<application>psql</application> program will display an ASCII-art
<application>psql</application> program will display an ASCII-art
table on the screen, client libraries will offer functions to
table on the screen, client libraries will offer functions to
retrieve individual rows and columns.) The select list
retrieve individual rows and columns.) The select list
...
@@ -36,21 +41,23 @@ SELECT * FROM table1;
...
@@ -36,21 +41,23 @@ SELECT * FROM table1;
expression happens to provide. A select list can also select a
expression happens to provide. A select list can also select a
subset of the available columns or even make calculations on the
subset of the available columns or even make calculations on the
columns before retrieving them; see <xref
columns before retrieving them; see <xref
linkend="queries-select-lists">. For example, if table1 has columns
linkend="queries-select-lists">. For example, if
named a, b, and c (and perhaps others) you can make the following
<literal>table1</literal> has columns named <literal>a</>,
query:
<literal>b</>, and <literal>c</> (and perhaps others) you can make
the following query:
<programlisting>
<programlisting>
SELECT a, b + c FROM table1;
SELECT a, b + c FROM table1;
</programlisting>
</programlisting>
(assuming that b and c are of a numeric data type).
(assuming that <literal>b</> and <literal>c</> are of a numerical
data type).
</para>
</para>
<para>
<para>
<literal>FROM table1</literal> is a particularly simple kind of
<literal>FROM table1</literal> is a particularly simple kind of
table expression. In general, table expressions can be complex
table expression: it reads just one table. In general, table
constructs of base tables, joins, and subqueries. But you can also
expressions can be complex constructs of base tables, joins, and
omit the table expression entirely and use the SELECT command as a
subqueries. But you can also omit the table expression entirely and
calculator:
use the <command>SELECT</command> command as a calculator:
<programlisting>
<programlisting>
SELECT 3 * 4;
SELECT 3 * 4;
</programlisting>
</programlisting>
...
@@ -62,52 +69,56 @@ SELECT random();
...
@@ -62,52 +69,56 @@ SELECT random();
</para>
</para>
</sect1>
</sect1>
<sect1 id="queries-table-expressions">
<sect1 id="queries-table-expressions">
<title>Table Expressions</title>
<title>Table Expressions</title>
<para>
<para>
A <firstterm>table expression</firstterm> specifies a table. The
A <firstterm>table expression</firstterm> computes a table. The
table expression contains a FROM clause that is optionally followed
table expression contains a <literal>FROM</> clause that is
by WHERE, GROUP BY, and HAVING clauses. Trivial table expressions
optionally followed by <literal>WHERE</>, <literal>GROUP BY</>, and
simply refer to a table on disk, a so-called base table, but more
The GROUP BY clause is used to group together rows in a table that
The <literal>GROUP BY</> clause is used to group together rows in
share the same values in all the columns listed. The order in
a table that share the same values in all the columns listed. The
which the columns are listed does not matter (as opposed to an
order in which the columns are listed does not matter. The
ORDER BY clause). The purpose is to reduce each group of rows
purpose is to reduce each group of rows sharing common values into
sharing common values into one group row that is representative of
one group row that is representative of all rows in the group.
all rows in the group. This is done to eliminate redundancy in
This is done to eliminate redundancy in the output and/or obtain
the output and/or obtain aggregates that apply to these groups.
aggregates that apply to these groups. For instance:
<screen>
<prompt>=></> <userinput>SELECT * FROM test1;</>
x | y
---+---
a | 3
c | 2
b | 5
a | 1
(4 rows)
<prompt>=></> <userinput>SELECT x FROM test1 GROUP BY x;</>
x
---
a
b
c
(3 rows)
</screen>
</para>
</para>
<para>
<para>
Once a table is grouped, columns that are not used in the
In the second query, we could not have written <literal>SELECT *
grouping cannot be referenced except in aggregate expressions,
FROM test1 GROUP BY x;</literal>, because there is no single value
since a specific value in those columns is ambiguous - which row
for the column <literal>y</> that could be associated with each
in the group should it come from? The grouped-by columns can be
group. In general, if a table is grouped, columns that are not
referenced in select list column expressions since they have a
used in the grouping cannot be referenced except in aggregate
known constant value per group. Aggregate functions on the
expressions, for example:
ungrouped columns provide values that span the rows of a group,
<screen>
not of the whole table. For instance, a
<prompt>=></> <userinput>SELECT x, sum(y) FROM test1 GROUP BY x;</>
<function>sum(sales)</function> on a table grouped by product code
x | sum
gives the total sales for each product, not the total sales on all
---+-----
products. Aggregates computed on the ungrouped columns are
a | 4
representative of the group, whereas individual values of an ungrouped
b | 5
column are not.
c | 2
(3 rows)
</screen>
Here <literal>sum()</literal> is an aggregate function that
computes a single value over the entire group. More information
about the available aggregate functions can be found in <xref
linkend="functions-aggregate">.
</para>
</para>
<para>
<para>
Example:
The grouped-by columns can be referenced in the select list since
they have a known constant value per group.
</para>
<note>
<para>
Grouping without aggregate expressions effectively calculates the
set of distinct values in a column. This can also be achieved
using the <literal>DISTINCT</> clause (see <xref
linkend="queries-distinct">).
</para>
</note>
<para>
Here is another example: A <function>sum(sales)</function> on a
table grouped by product code gives the total sales for each
product, not the total sales on all products.
<programlisting>
<programlisting>
SELECT pid, p.name, (sum(s.units) * p.price) AS sales
SELECT product_id, p.name, (sum(s.units) * p.price) AS sales
FROM products p LEFT JOIN sales s USING ( pid )
FROM products p LEFT JOIN sales s USING (product_id)
GROUP BY pid, p.name, p.price;
GROUP BY pid, p.name, p.price;
</programlisting>
</programlisting>
In this example, the columns <literal>pid</literal>, <literal>p.name</literal>, and <literal>p.price</literal> must be in
In this example, the columns <literal>pid</literal>,
the GROUP BY clause since they are referenced in the query select
<literal>p.name</literal>, and <literal>p.price</literal> must be
list. The column s.units does not have to be in the GROUP BY list
in the <literal>GROUP BY</> clause since they are referenced in
since it is only used in an aggregate expression
the query select list. (Depending on how exactly the products
table is set up, name and price may be fully dependent on the
product ID, so the additional groups could theoretically be
unnecessary, but this is not implemented yet.) The column
<literal>s.units</> does not have to be in the <literal>GROUP
BY</> list since it is only used in an aggregate expression
(<function>sum()</function>), which represents the group of sales
(<function>sum()</function>), which represents the group of sales
of a product. For each product, a summary row is returned about
of a product. For each product, a summary row is returned about
all sales of the product.
all sales of the product.
</para>
</para>
<para>
<para>
In strict SQL, GROUP BY can only group by columns of the source
In strict SQL, <literal>GROUP BY</> can only group by columns of
table but <productname>PostgreSQL</productname> extends this to also allow GROUP BY to group by
the source table but <productname>PostgreSQL</productname> extends
select columns in the query select list. Grouping by value
this to also allow <literal>GROUP BY</> to group by columns in the
expressions instead of simple column names is also allowed.
select list. Grouping by value expressions instead of simple
column names is also allowed.
</para>
</para>
<para>
<para>
If a table has been grouped using a <literal>GROUP BY</literal>
clause, but then only certain groups are of interest, the
<literal>HAVING</literal> clause can be used, much like a
<literal>WHERE</> clause, to eliminate groups from a grouped
table. The syntax is:
<synopsis>
<synopsis>
SELECT <replaceable>select_list</replaceable> FROM ... <optional>WHERE ...</optional> GROUP BY ... HAVING <replaceable>boolean_expression</replaceable>
SELECT <replaceable>select_list</replaceable> FROM ... <optional>WHERE ...</optional> GROUP BY ... HAVING <replaceable>boolean_expression</replaceable>
</synopsis>
</synopsis>
If a table has been grouped using a GROUP BY clause, but then only
Expressions in the <literal>HAVING</> clause can refer both to
certain groups are of interest, the HAVING clause can be used,
grouped expressions and to ungrouped expression (which necessarily
much like a WHERE clause, to eliminate groups from a grouped
involve an aggregate function).
table. <productname>PostgreSQL</productname> allows a HAVING clause to be
used without a GROUP BY, in which case it acts like another WHERE
clause, but the point in using HAVING that way is not clear. A good
rule of thumb is that a HAVING condition should refer to the results
of aggregate functions. A restriction that does not involve an
aggregate is more efficiently expressed in the WHERE clause.
</para>
</para>
<para>
<para>
Example:
Example:
<screen>
<prompt>=></> <userinput>SELECT x, sum(y) FROM test1 GROUP BY x HAVING sum(y) > 3;</>
x | sum
---+-----
a | 4
b | 5
(2 rows)
<prompt>=></> <userinput>SELECT x, sum(y) FROM test1 GROUP BY x HAVING x < 'c';</>
x | sum
---+-----
a | 4
b | 5
(2 rows)
</screen>
</para>
<para>
Again, a more realistic example:
<programlisting>
<programlisting>
SELECT pid AS "Products",
SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit
p.name AS "Over 5000",
FROM products p LEFT JOIN sales s USING (pid)
(sum(s.units) * (p.price - p.cost)) AS "Past Month Profit"
FROM products p LEFT JOIN sales s USING ( pid )
WHERE s.date > CURRENT_DATE - INTERVAL '4 weeks'
WHERE s.date > CURRENT_DATE - INTERVAL '4 weeks'
GROUP BY pid, p.name, p.price, p.cost
GROUP BY product_id, p.name, p.price, p.cost
HAVING sum(p.price * s.units) > 5000;
HAVING sum(p.price * s.units) > 5000;
</programlisting>
</programlisting>
In the example above, the WHERE clause is selecting rows by a
In the example above, the <literal>WHERE</> clause is selecting
column that is not grouped, while the HAVING clause
rows by a column that is not grouped, while the <literal>HAVING</>
restricts the output to groups with total gross sales over 5000.
clause restricts the output to groups with total gross sales over
5000. Note that the aggregate expressions do not necessarily need
to be the same everywhere.
</para>
</para>
</sect2>
</sect2>
</sect1>
</sect1>
...
@@ -651,37 +824,50 @@ SELECT pid AS "Products",
...
@@ -651,37 +824,50 @@ SELECT pid AS "Products",
tables, views, eliminating rows, grouping, etc. This table is
tables, views, eliminating rows, grouping, etc. This table is
finally passed on to processing by the <firstterm>select list</firstterm>. The select
finally passed on to processing by the <firstterm>select list</firstterm>. The select
list determines which <emphasis>columns</emphasis> of the
list determines which <emphasis>columns</emphasis> of the
intermediate table are actually output. The simplest kind of select list
intermediate table are actually output.
is <literal>*</literal> which emits all columns that the table
</para>
expression produces. Otherwise, a select list is a comma-separated
list of value expressions (as defined in <xref
<sect2 id="queries-select-list-items">
linkend="sql-expressions">). For instance, it could be a list of
<title>Select List Items</title>
column names:
<para>
The simplest kind of select list is <literal>*</literal> which
emits all columns that the table expression produces. Otherwise,
a select list is a comma-separated list of value expressions (as
defined in <xref linkend="sql-expressions">). For instance, it
could be a list of column names:
<programlisting>
<programlisting>
SELECT a, b, c FROM ...
SELECT a, b, c FROM ...
</programlisting>
</programlisting>
The columns names a, b, and c are either the actual names of the
The columns names <literal>a</>, <literal>b</>, and <literal>c</>
columns of tables referenced in the FROM clause, or the aliases
are either the actual names of the columns of tables referenced
given to them as explained in <xref linkend="queries-table-aliases">.
in the <literal>FROM</> clause, or the aliases given to them as
The name space available in the select list is the same as in the
explained in <xref linkend="queries-table-aliases">. The name
WHERE clause (unless grouping is used, in which case it is the same
space available in the select list is the same as in the
as in the HAVING clause). If more than one table has a column of
<literal>WHERE</> clause, unless grouping is used, in which case
the same name, the table name must also be given, as in
it is the same as in the <literal>HAVING</> clause.
</para>
<para>
If more than one table has a column of the same name, the table
name must also be given, as in
<programlisting>
<programlisting>
SELECT tbl1.a, tbl2.b, tbl1.c FROM ...
SELECT tbl1.a, tbl2.b, tbl1.c FROM ...
</programlisting>
</programlisting>
(see also <xref linkend="queries-where">).
(See also <xref linkend="queries-where">.)
</para>
</para>
<para>
<para>
If an arbitrary value expression is used in the select list, it
If an arbitrary value expression is used in the select list, it
conceptually adds a new virtual column to the returned table. The
conceptually adds a new virtual column to the returned table. The
value expression is evaluated once for each retrieved
value expression is evaluated once for each retrieved row, with
row, with the row's values substituted for any column references. But
the row's values substituted for any column references. But the
the expressions in the select list do not have to reference any
expressions in the select list do not have to reference any
columns in the table expression of the FROM clause; they could be
columns in the table expression of the <literal>FROM</> clause;
constant arithmetic expressions as well, for instance.
they could be constant arithmetic expressions as well, for
instance.
</para>
</para>
</sect2>
<sect2 id="queries-column-labels">
<sect2 id="queries-column-labels">
<title>Column Labels</title>
<title>Column Labels</title>
...
@@ -712,10 +898,10 @@ SELECT a AS value, b + c AS sum FROM ...
...
@@ -712,10 +898,10 @@ SELECT a AS value, b + c AS sum FROM ...
<note>
<note>
<para>
<para>
The naming of output columns here is different from that done in
The naming of output columns here is different from that done in
the FROM clause (see <xref linkend="queries-table-aliases">). This
the <literal>FROM</> clause (see <xref
pipeline will in fact allow you to rename the same column twice,
linkend="queries-table-aliases">). This pipeline will in fact
but the name chosen in the select list is the one that will be
allow you to rename the same column twice, but the name chosen in
passed on.
the select list is the one that will be passed on.
</para>
</para>
</note>
</note>
</sect2>
</sect2>
...
@@ -730,12 +916,12 @@ SELECT a AS value, b + c AS sum FROM ...
...
@@ -730,12 +916,12 @@ SELECT a AS value, b + c AS sum FROM ...
<para>
<para>
After the select list has been processed, the result table may
After the select list has been processed, the result table may
optionally be subject to the elimination of duplicates. The
optionally be subject to the elimination of duplicates. The
<token>DISTINCT</token> key word is written directly after the
<literal>DISTINCT</literal> key word is written directly after the
