diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index c4a8ca8d8a..7dbad462a5 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -118,10 +118,12 @@ FROM table_reference , table_r A table reference can be a table name (possibly schema-qualified), - or a derived table such as a subquery, a table join, or complex - combinations of these. If more than one table reference is listed - in the FROM clause they are cross-joined (see below) - to form the intermediate virtual table that can then be subject to + or a derived table such as a subquery, a JOIN construct, or + complex combinations of these. If more than one table reference is + listed in the FROM clause, the tables are cross-joined + (that is, the Cartesian product of their rows is formed; see below). + The result of the FROM list is an intermediate virtual + table that can then be subject to transformations by the WHERE, GROUP BY, and HAVING clauses and is finally the result of the overall table expression. @@ -161,6 +163,16 @@ FROM table_reference , table_r A joined table is a table derived from two other (real or derived) tables according to the rules of the particular join type. Inner, outer, and cross-joins are available. + The general syntax of a joined table is + +T1 join_type T2 join_condition + + Joins of all types can be chained together, or nested: either or + both T1 and + T2 can be joined tables. Parentheses + can be used around JOIN clauses to control the join + order. In the absence of parentheses, JOIN clauses + nest left-to-right. @@ -197,10 +209,28 @@ FROM table_reference , table_r FROM T1 CROSS JOIN T2 is equivalent to - FROM T1, - T2. It is also equivalent to FROM T1 INNER JOIN T2 ON TRUE (see below). + It is also equivalent to + FROM T1, + T2. + + + This latter equivalence does not hold exactly when more than two + tables appear, because JOIN binds more tightly than + comma. For example + FROM T1 CROSS JOIN + T2 INNER JOIN T3 + ON condition + is not the same as + FROM T1, + T2 INNER JOIN T3 + ON condition + because the condition can + reference T1 in the first case but not + the second. + + @@ -240,76 +270,6 @@ FROM table_reference , table_r match, as explained in detail below. - - The ON clause is the most general kind of join - condition: it takes a Boolean value expression of the same - kind as is used in a WHERE clause. A pair of rows - from T1 and T2 match if the - ON expression evaluates to true. - - - - The USING clause allows you to take advantage of - the specific situation where both sides of the join use the - same name for the joining columns. It takes a - comma-separated list of the shared column names - and forms a join using the equals operator. Furthermore, the - output of JOIN USING has one column for each of the - listed columns, followed by the remaining columns from each table. - - - The output column difference between ON and - USING when invoking SELECT * is: - - - - ON - all columns from T1 followed - by all columns from T2 - - - - - USING - all join columns, one copy each - and in the listed order, followed by non-join columns - in T1 followed by non-join columns in - T2 - - - - - Examples provided below - - - - - - - join - natural - - - natural join - - Finally, NATURAL is a shorthand form of - USING: it forms a USING list - consisting of all column names that appear in both - input tables. As with USING, these columns appear - only once in the output table. If there are no common - columns, NATURAL behaves like - CROSS JOIN. - - - - - USING is reasonably safe from column changes - in the joined relations since only the specific columns mentioned - are considered. NATURAL is considerably more problematic - if you are referring to relations only by name (views and tables) - since any schema changes to either relation that cause a new matching - column name to be present will cause the join to consider that new column. - - - The possible types of qualified join are: @@ -387,19 +347,70 @@ FROM table_reference , table_r + + + The ON clause is the most general kind of join + condition: it takes a Boolean value expression of the same + kind as is used in a WHERE clause. A pair of rows + from T1 and T2 match if the + ON expression evaluates to true. + + + + The USING clause is a shorthand that allows you to take + advantage of the specific situation where both sides of the join use + the same name for the joining column(s). It takes a + comma-separated list of the shared column names + and forms a join condition that includes an equality comparison + for each one. For example, joining T1 + and T2 with USING (a, b) produces + the join condition ON T1.a + = T2.a AND T1.b + = T2.b. + + + + Furthermore, the output of JOIN USING suppresses + redundant columns: there is no need to print both of the matched + columns, since they must have equal values. While JOIN + ON produces all columns from T1 followed by all + columns from T2, JOIN USING produces one + output column for each of the listed column pairs (in the listed + order), followed by any remaining columns from T1, + followed by any remaining columns from T2. + + + + + join + natural + + + natural join + + Finally, NATURAL is a shorthand form of + USING: it forms a USING list + consisting of all column names that appear in both + input tables. As with USING, these columns appear + only once in the output table. If there are no common + column names, NATURAL behaves like + CROSS JOIN. + + + + + USING is reasonably safe from column changes + in the joined relations since only the listed columns + are combined. NATURAL is considerably more risky since + any schema changes to either relation that cause a new matching + column name to be present will cause the join to combine that new + column as well. + + - - Joins of all types can be chained together or nested: either or - both T1 and - T2 can be joined tables. Parentheses - can be used around JOIN clauses to control the join - order. In the absence of parentheses, JOIN clauses - nest left-to-right. - - To put this together, assume we have tables t1: @@ -516,6 +527,8 @@ FROM table_reference , table_r clause is processed before the join, while a restriction placed in the WHERE clause is processed after the join. + That does not matter with inner joins, but it matters a lot with outer + joins.