diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index a0188494981..6740d9d6f76 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,47 +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 for them. - - - - USING is a shorthand notation: it takes a - comma-separated list of column names, which the joined tables - must have in common, and forms a join condition specifying - equality of each of these pairs of columns. Furthermore, the - output of JOIN USING has one column for each of - the equated pairs of input columns, followed by the - remaining columns from each table. Thus, USING (a, b, - c) is equivalent to ON (t1.a = t2.a AND - t1.b = t2.b AND t1.c = t2.c) with the exception that - if ON is used there will be two columns - a, b, and c in the result, - whereas with USING there will be only one of each - (and they will appear first if SELECT * is used). - - - - - 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. - - The possible types of qualified join are: @@ -358,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: @@ -487,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.