diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 9444f5f6e6e..f8f1ebabd02 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1,5 +1,5 @@ @@ -41,11 +41,6 @@ where from_item can be one of: from_item [ NATURAL ] join_type from_item [ ON join_condition | USING ( join_column [, ...] ) ] -FIXME: This last syntax is incorrect if the join type is an -INNER or OUTER join (in which case one of NATURAL, ON ..., or USING -... is mandatory, not optional). What's the best way to fix -this? - @@ -107,7 +102,7 @@ this? - The actual output rows are computed the + The actual output rows are computed using the SELECT output expressions for each selected row. (See @@ -125,15 +120,6 @@ this? - - - If the LIMIT or OFFSET - clause is specified, the SELECT statement - only returns a subset of the result rows. (See below.) - - - DISTINCT eliminates duplicate rows from the @@ -145,6 +131,15 @@ this? + + + If the LIMIT or OFFSET + clause is specified, the SELECT statement + only returns a subset of the result rows. (See below.) + + + The FOR UPDATE clause causes the @@ -291,17 +286,21 @@ this? - A JOIN clause, combines two - FROM items. (Use parentheses if necessary to - determine the order of nesting.) + A JOIN clause combines two + FROM items. Use parentheses if necessary to + determine the order of nesting. In the absence of parentheses, + JOINs nest left-to-right. In any case + JOIN binds more tightly than the commas + separating FROM items. CROSS JOIN and INNER JOIN - produce a simple Cartesian product, the same as you get from - listing the two items at the top level of FROM. + produce a simple Cartesian product, the same result as you get from + listing the two items at the top level of FROM, + but restricted by the join condition (if any). CROSS JOIN is equivalent to INNER JOIN ON - (true), that is, no rows are removed by qualification. + (TRUE), that is, no rows are removed by qualification. These join types are just a notational convenience, since they do nothing you couldn't do with plain FROM and WHERE. @@ -315,7 +314,7 @@ this? condition. This left-hand row is extended to the full width of the joined table by inserting null values for the right-hand columns. Note that only the JOIN - clauses own condition is considered while deciding which rows + clause's own condition is considered while deciding which rows have matches. Outer conditions are applied afterwards. @@ -410,7 +409,7 @@ GROUP BY expression [, ...] expressions. expression can be an input column name, or the name or ordinal number of an output column - (SELECT list), or it can be an arbitrary + (SELECT list item), or an arbitrary expression formed from input-column values. In case of ambiguity, a GROUP BY name will be interpreted as an input-column name rather than an output column name. @@ -497,7 +496,7 @@ HAVING condition Currently, FOR UPDATE may not be specified either for - a UNION result or for the inputs of UNION. + a UNION result or for any input of a UNION. @@ -613,7 +612,7 @@ ORDER BY expression [ ASC | DESC | expression can be the name or ordinal number of an output column - (SELECT list), or it can be an arbitrary + (SELECT list item), or it can be an arbitrary expression formed from input-column values. @@ -623,7 +622,7 @@ ORDER BY expression [ ASC | DESC | equal according to the leftmost expression, the are compared according to the next expression and so on. If they are equal according to all specified expressions, they are returned in - random order. + an implementation-dependent order. @@ -660,7 +659,7 @@ SELECT name FROM distributors ORDER BY code; Optionally one may add the key word ASC (ascending) or - DESC (descending) after each expression in the + DESC (descending) after any expression in the ORDER BY clause. If not specified, ASC is assumed by default. Alternatively, a specific ordering operator name may be specified in the USING clause. @@ -689,15 +688,18 @@ SELECT name FROM distributors ORDER BY code; The LIMIT clause consists of two independent - clauses: + sub-clauses: LIMIT { count | ALL } OFFSET start count specifies the - maximum number of rows to return, and start specifies the number of rows - to skip before starting to return rows. + to skip before starting to return rows. When both are specified, + start rows are skipped + before starting to count the count rows to be returned. @@ -754,6 +756,13 @@ SELECT DISTINCT ON (location) location, time, report of time values for each location, we'd have gotten a report from an unpredictable time for each location. + + + The DISTINCT ON expression(s) must match the leftmost + ORDER BY expression(s). The ORDER BY clause + will normally contain additional expression(s) that determine the + desired precedence of rows within each DISTINCT ON group. + @@ -889,10 +898,10 @@ SELECT * FROM distributors ORDER BY 2; - This example shows how to obtain the union of the tables + The next example shows how to obtain the union of the tables distributors and actors, restricting the results to those that begin - with letter W in each table. Only distinct rows are wanted, so the + with the letter W in each table. Only distinct rows are wanted, so the key word ALL is omitted. @@ -925,7 +934,7 @@ SELECT actors.name This example shows how to use a function in the FROM - clause, both with and without a column definition list. + clause, both with and without a column definition list: CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS ' @@ -1048,7 +1057,8 @@ SELECT distributors.* FROM distributors d, distributors distributors; - SQL99 uses a slightly different definition which is not upward compatible + SQL99 uses a slightly different definition which is not entirely upward + compatible with SQL92. In most cases, however, PostgreSQL will interpret an ORDER BY or GROUP BY expression the same way SQL99 does.