From 86392b06b8686cf2cfac378ee1b51faa0efb0c53 Mon Sep 17 00:00:00 2001
From: Andy Grove <andygrove73@gmail.com>
Date: Sat, 13 Aug 2022 11:08:40 -0600
Subject: [PATCH 1/5] Add user guide section on subquery support

---
 docs/source/user-guide/sql/index.rst     |  1 +
 docs/source/user-guide/sql/subqueries.md | 98 ++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 docs/source/user-guide/sql/subqueries.md

diff --git a/docs/source/user-guide/sql/index.rst b/docs/source/user-guide/sql/index.rst
index 97753d708e1b..4015864b4701 100644
--- a/docs/source/user-guide/sql/index.rst
+++ b/docs/source/user-guide/sql/index.rst
@@ -23,6 +23,7 @@ SQL Reference
 
    sql_status
    select
+   subqueries
    ddl
    aggregate_functions
    scalar_functions
diff --git a/docs/source/user-guide/sql/subqueries.md b/docs/source/user-guide/sql/subqueries.md
new file mode 100644
index 000000000000..820d97e72f43
--- /dev/null
+++ b/docs/source/user-guide/sql/subqueries.md
@@ -0,0 +1,98 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Subqueries
+
+DataFusion supports `EXISTS`, `IN`, and Scalar Subqueries.
+
+The examples below are based on the following table.
+
+```sql
+❯ select * from x;
++----------+----------+
+| column_1 | column_2 |
++----------+----------+
+| 1        | 2        |
++----------+----------+
+```
+
+## EXISTS
+
+The `EXISTS` syntax can be used to find all rows in a relation where a correlated subquery produces one or more matches
+for that row. Only correlated subqueries are supported.
+
+```sql
+❯ select * from x y where exists (select * from x where x.column_1 = y.column_1);
++----------+----------+
+| column_1 | column_2 |
++----------+----------+
+| 1        | 2        |
++----------+----------+
+1 row in set.
+```
+
+## NOT EXISTS
+
+The `NOT EXISTS` syntax can be used to find all rows in a relation where a correlated subquery produces zero matches
+for that row. Only correlated subqueries are supported.
+
+```sql
+❯ select * from x y where not exists (select * from x where x.column_1 = y.column_1);
+0 rows in set.
+```
+
+## IN
+
+The `IN` syntax can be used to find all rows in a relation where a given expression's value can be found in the
+results of a correlated subquery. Only correlated subqueries are supported.
+
+```sql
+❯ select * from x where column_1 in (select column_1 from x);
++----------+----------+
+| column_1 | column_2 |
++----------+----------+
+| 1        | 2        |
++----------+----------+
+1 row in set.
+```
+
+## NOT IN
+
+The `NOT IN` syntax can be used to find all rows in a relation where a given expression's value can not be found in the
+results of a correlated subquery. Only correlated subqueries are supported.
+
+```sql
+❯ select * from x where column_1 not in (select column_1 from x);
+0 rows in set.
+```
+
+## Scalar Subquery
+
+A scalar subquery can be used to produce a single value that can be used in many different contexts in a query. Here
+is an example of a filter using a scalar subquery. Only correlated subqueries are supported.
+
+```sql
+❯ select * from x y where column_1 < (select sum(column_2) from x where x.column_1 = y.column_1);
++----------+----------+
+| column_1 | column_2 |
++----------+----------+
+| 1        | 2        |
++----------+----------+
+1 row in set.
+```

From 528e580a1b794745d6953aa3ea802f28f92e9791 Mon Sep 17 00:00:00 2001
From: Andy Grove <andygrove73@gmail.com>
Date: Mon, 15 Aug 2022 13:23:30 -0600
Subject: [PATCH 2/5] Update docs/source/user-guide/sql/subqueries.md

Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>
---
 docs/source/user-guide/sql/subqueries.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/user-guide/sql/subqueries.md b/docs/source/user-guide/sql/subqueries.md
index 820d97e72f43..10ebef1634ea 100644
--- a/docs/source/user-guide/sql/subqueries.md
+++ b/docs/source/user-guide/sql/subqueries.md
@@ -19,7 +19,7 @@
 
 # Subqueries
 
-DataFusion supports `EXISTS`, `IN`, and Scalar Subqueries.
+DataFusion supports `EXISTS`, `NOT EXISTS`, `IN`, `NOT IN` and Scalar Subqueries.
 
 The examples below are based on the following table.
 

From c0b2a8c0d7b2b7b3df84ff77f5ad30b3d66f738c Mon Sep 17 00:00:00 2001
From: Andy Grove <andygrove73@gmail.com>
Date: Mon, 15 Aug 2022 13:24:35 -0600
Subject: [PATCH 3/5] Update docs/source/user-guide/sql/subqueries.md

Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>
---
 docs/source/user-guide/sql/subqueries.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/user-guide/sql/subqueries.md b/docs/source/user-guide/sql/subqueries.md
index 10ebef1634ea..b7d5b1b0fea5 100644
--- a/docs/source/user-guide/sql/subqueries.md
+++ b/docs/source/user-guide/sql/subqueries.md
@@ -60,7 +60,7 @@ for that row. Only correlated subqueries are supported.
 ## IN
 
 The `IN` syntax can be used to find all rows in a relation where a given expression's value can be found in the
-results of a correlated subquery. Only correlated subqueries are supported.
+results of a correlated subquery. 
 
 ```sql
 ❯ select * from x where column_1 in (select column_1 from x);

From e7ef39f09d394a1e5107d1c3d06a9470eaec9141 Mon Sep 17 00:00:00 2001
From: Andy Grove <andygrove73@gmail.com>
Date: Mon, 15 Aug 2022 13:24:43 -0600
Subject: [PATCH 4/5] Update docs/source/user-guide/sql/subqueries.md

Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>
---
 docs/source/user-guide/sql/subqueries.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/user-guide/sql/subqueries.md b/docs/source/user-guide/sql/subqueries.md
index b7d5b1b0fea5..7ec0d555b52b 100644
--- a/docs/source/user-guide/sql/subqueries.md
+++ b/docs/source/user-guide/sql/subqueries.md
@@ -75,7 +75,7 @@ results of a correlated subquery.
 ## NOT IN
 
 The `NOT IN` syntax can be used to find all rows in a relation where a given expression's value can not be found in the
-results of a correlated subquery. Only correlated subqueries are supported.
+results of a correlated subquery.
 
 ```sql
 ❯ select * from x where column_1 not in (select column_1 from x);

From 627523b0b25fed8a27fa5dce9c4941141b0fcc4f Mon Sep 17 00:00:00 2001
From: Andy Grove <andygrove73@gmail.com>
Date: Mon, 15 Aug 2022 13:27:38 -0600
Subject: [PATCH 5/5] prettier

---
 docs/source/user-guide/sql/subqueries.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/user-guide/sql/subqueries.md b/docs/source/user-guide/sql/subqueries.md
index 7ec0d555b52b..478fab7e7c2d 100644
--- a/docs/source/user-guide/sql/subqueries.md
+++ b/docs/source/user-guide/sql/subqueries.md
@@ -60,7 +60,7 @@ for that row. Only correlated subqueries are supported.
 ## IN
 
 The `IN` syntax can be used to find all rows in a relation where a given expression's value can be found in the
-results of a correlated subquery. 
+results of a correlated subquery.
 
 ```sql
 ❯ select * from x where column_1 in (select column_1 from x);