This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git
The following commit(s) were added to refs/heads/master by this push:
new 4cf0cf0dc User Guide: Add documentation for JOIN syntax (#3130)
4cf0cf0dc is described below
commit 4cf0cf0dc58b9c5ac96288199b04f6478b4563fa
Author: Andy Grove <[email protected]>
AuthorDate: Mon Aug 15 13:19:25 2022 -0600
User Guide: Add documentation for JOIN syntax (#3130)
* Documentation for JOIN syntax
* revert Cargo.lock
* prettier
---
docs/source/user-guide/sql/select.md | 87 ++++++++++++++++++++++++++++++++++++
1 file changed, 87 insertions(+)
diff --git a/docs/source/user-guide/sql/select.md
b/docs/source/user-guide/sql/select.md
index 49399c93c..008981fde 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 [, ...] ] <br/>
[SELECT](#select-clause) [ ALL | DISTINCT ] select_expr [, ...] <br/>
[ [FROM](#from-clause) from_item [, ...] ] <br/>
+[ [JOIN](#join-clause) join_item [, ...] ] <br/>
[ [WHERE](#where-clause) condition ] <br/>
[ [GROUP BY](#group-by-clause) grouping_element [, ...] ] <br/>
[ [HAVING](#having-clause) condition] <br/>
@@ -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:
