diff --git a/docs/source/user-guide/sql/select.md b/docs/source/user-guide/sql/select.md index 49399c93c60d..008981fde0d3 100644 --- a/docs/source/user-guide/sql/select.md +++ b/docs/source/user-guide/sql/select.md @@ -28,6 +28,7 @@ DataFusion supports the following syntax for queries: [ [WITH](#with-clause) with_query [, ...] ]
[SELECT](#select-clause) [ ALL | DISTINCT ] select_expr [, ...]
[ [FROM](#from-clause) from_item [, ...] ]
+[ [JOIN](#join-clause) join_item [, ...] ]
[ [WHERE](#where-clause) condition ]
[ [GROUP BY](#group-by-clause) grouping_element [, ...] ]
[ [HAVING](#having-clause) condition]
@@ -77,6 +78,92 @@ Example: SELECT a FROM table WHERE a > 10 ``` +## JOIN clause + +DataFusion supports `INNER JOIN`, `LEFT OUTER JOIN`, `RIGHT OUTER JOIN`, `FULL OUTER JOIN`, and `CROSS JOIN`. + +The following examples are based on this table: + +```sql +select * from x; ++----------+----------+ +| column_1 | column_2 | ++----------+----------+ +| 1 | 2 | ++----------+----------+ +``` + +### INNER JOIN + +The keywords `JOIN` or `INNER JOIN` define a join that only shows rows where there is a match in both tables. + +```sql +❯ select * from x inner join x y ON x.column_1 = y.column_1; ++----------+----------+----------+----------+ +| column_1 | column_2 | column_1 | column_2 | ++----------+----------+----------+----------+ +| 1 | 2 | 1 | 2 | ++----------+----------+----------+----------+ +``` + +### LEFT OUTER JOIN + +The keywords `LEFT JOIN` or `LEFT OUTER JOIN` define a join that includes all rows from the left table even if there +is not a match in the right table. When there is no match, null values are produced for the right side of the join. + +```sql +❯ select * from x left join x y ON x.column_1 = y.column_2; ++----------+----------+----------+----------+ +| column_1 | column_2 | column_1 | column_2 | ++----------+----------+----------+----------+ +| 1 | 2 | | | ++----------+----------+----------+----------+ +``` + +### RIGHT OUTER JOIN + +The keywords `RIGHT JOIN` or `RIGHT OUTER JOIN` define a join that includes all rows from the right table even if there +is not a match in the left table. When there is no match, null values are produced for the left side of the join. + +```sql +❯ select * from x right join x y ON x.column_1 = y.column_2; ++----------+----------+----------+----------+ +| column_1 | column_2 | column_1 | column_2 | ++----------+----------+----------+----------+ +| | | 1 | 2 | ++----------+----------+----------+----------+ +``` + +### FULL OUTER JOIN + +The keywords `FULL JOIN` or `FULL OUTER JOIN` define a join that is effectively a union of a `LEFT OUTER JOIN` and +`RIGHT OUTER JOIN`. It will show all rows from the left and right side of the join and will produce null values on +either side of the join where there is not a match. + +```sql +❯ select * from x full outer join x y ON x.column_1 = y.column_2; ++----------+----------+----------+----------+ +| column_1 | column_2 | column_1 | column_2 | ++----------+----------+----------+----------+ +| 1 | 2 | | | +| | | 1 | 2 | ++----------+----------+----------+----------+ +``` + +### CROSS JOIN + +A cross join produces a cartesian product that matches every row in the left side of the join with every row in the +right side of the join. + +```sql +❯ select * from x cross join x y; ++----------+----------+----------+----------+ +| column_1 | column_2 | column_1 | column_2 | ++----------+----------+----------+----------+ +| 1 | 2 | 1 | 2 | ++----------+----------+----------+----------+ +``` + ## GROUP BY clause Example: