Update the documentation for SQL joins

docs/sphinx/source/reference/Joins.rst

@@ -4,53 +4,49 @@ Joins
 
 .. _joins:
 
-Joins combine rows from two or more tables based on related column. FDB Record Layer supports INNER JOIN and joins using comma-separated table references in the FROM clause with join conditions specified in the WHERE clause.
+Joins combine rows from two or more tables based on a related column. The FDB Record Layer supports the standard SQL join keywords ``INNER JOIN`` (or just ``JOIN``), ``LEFT OUTER JOIN`` (or ``LEFT JOIN``), and ``RIGHT OUTER JOIN`` (or ``RIGHT JOIN``). As an alternative to the ``INNER JOIN`` syntax, inner joins can also be expressed using comma-separated table references in the ``FROM`` clause with join conditions specified in the ``WHERE`` clause.
 
 .. important::
 
-   FDB Record Layer **supports** only one standard SQL JOIN keyword ``INNER JOIN`` (or just ``JOIN``).
-
-   FDB Record Layer **does not support** other standard SQL JOIN keywords (``LEFT JOIN``, ``RIGHT JOIN``, ``OUTER JOIN``, etc.). Use the comma-separated FROM clause instead.
+   The FDB Record Layer **does not support** the ``FULL OUTER JOIN`` and ``CROSS JOIN`` variants.
 
 Basic Join Syntax
 =================
 
 Cross Join (Cartesian Product)
 -------------------------------
 
-FDB Record Layer **does not support** ``CROSS JOIN`` keyword.
-List multiple tables separated by commas instead:
+The FDB Record Layer **does not support** the ``CROSS JOIN`` keyword. List multiple tables separated by commas instead:
 
 .. code-block:: sql
 
     SELECT columns FROM table1, table2
 
 This produces a Cartesian product of all rows from both tables.
 
-Inner Join On Condition
----------------------------
+Inner Join with ON
+------------------
 
-Use ON clause to specify join conditions:
+Use the ``ON`` clause to specify join conditions:
 
 .. code-block:: sql
 
     SELECT columns
     FROM table1 INNER JOIN table2
     ON table1.column = table2.column
 
-This is equivalent to SELECT FROM comma-separated sources with WHERE Clause:
+This is equivalent to a ``SELECT`` from comma-separated sources with a ``WHERE`` clause:
 
 .. code-block:: sql
 
     SELECT columns
     FROM table1, table2
     WHERE table1.column = table2.column
 
-Inner Join Using(Column)
----------------------------
+Inner Join with USING
+---------------------
 
-The special case is used when joining tables have the same name column(s).
-The column(s) are specified in the USING() clause:
+The ``USING`` clause is a shorthand for when the joined tables share identically named columns. The columns are specified in the ``USING`` clause:
 
 .. code-block:: sql
 
@@ -60,7 +56,7 @@ The column(s) are specified in the USING() clause:
     SELECT columns
     FROM a INNER JOIN b USING(c1)
 
-It is equivalent to:
+This is equivalent to:
 
 .. code-block:: sql
 
@@ -74,7 +70,7 @@ And also equivalent to:
     SELECT columns
     FROM a, b WHERE a.c1 = b.c1
 
-An important feature of ``INNER JOIN USING`` is that it hides duplicated columns from the output:
+An important feature of ``INNER JOIN … USING`` is that it hides duplicate columns from the output:
 
 .. code-block:: sql
 
@@ -84,7 +80,7 @@ An important feature of ``INNER JOIN USING`` is that it hides duplicated columns
     SELECT *
     FROM a INNER JOIN b USING(c1)
 
-In this case ``SELECT *`` returns only three columns:
+In this case, ``SELECT *`` returns only three columns:
 
 .. list-table::
     :header-rows: 0
@@ -93,7 +89,7 @@ In this case ``SELECT *`` returns only three columns:
       - `c2`
       - `c3`
 
-However, the joining columns can be accessed directly using qualified names:
+However, the joining columns can still be accessed using qualified names:
 
 .. code-block:: sql
 
@@ -108,7 +104,7 @@ This returns two identical columns:
     * - `a.c1`
       - `b.c1`
 
-``INNER JOIN USING`` maintains the standard order of the output from left to right excluding duplicates:
+``INNER JOIN USING`` maintains the standard column order from left to right, excluding duplicates:
 
 .. code-block:: sql
 
@@ -118,7 +114,7 @@ This returns two identical columns:
     SELECT *
     FROM a INNER JOIN b USING(c1, c5)
 
-Returns 6 columns: all columns from ``a`` (c1, c2, c5, c6) and all columns from ``b`` excluding duplicates (c3, c7):
+This returns six columns: all columns from ``a`` (c1, c2, c5, c6) followed by the non-duplicate columns from ``b`` (c3, c7).
 
 .. list-table::
     :header-rows: 0
@@ -136,7 +132,7 @@ Examples
 Setup
 -----
 
-For these examples, assume we have the following tables:
+For these examples, assume the following tables:
 
 .. code-block:: sql
 
@@ -203,8 +199,8 @@ Join employees with their departments:
     * - :json:`"Emily"`
       - :json:`"Martinez"`
 
-Consecutive Join
---------------
+Consecutive Joins
+-----------------
 
 Join across three tables to find departments and their projects:
 
@@ -226,7 +222,7 @@ Join across three tables to find departments and their projects:
     * - :json:`"Marketing"`
       - :json:`"SEO"`
 
-Joining the result of first join (employees and departments) to projects;
+The result of the first join (employees and departments) is joined to projects.
 
 Join with Subquery
 ------------------
@@ -281,7 +277,7 @@ Join subqueries that themselves contain joins:
     * - :json:`"Marketing"`
       - :json:`"SEO"`
 
-The subquery first joins employees with departments, then the result is joined with projects.
+The subquery first joins employees with departments; the result is then joined with projects.
 
 Join with CTEs
 --------------
@@ -305,7 +301,7 @@ Join a table to itself:
 
     SELECT * FROM Table1, Table1 WHERE col1 = 10
 
-This self-join can be used to find relationships within the same table. Use aliases to distinguish between the two references:
+A self-join can be used to find relationships within the same table. Use aliases to distinguish between the two references:
 
 .. code-block:: sql
 
@@ -317,7 +313,7 @@ This self-join can be used to find relationships within the same table. Use alia
 Semi-Join with EXISTS
 ----------------------
 
-Use EXISTS to implement a semi-join (find rows that have matching rows in another table):
+Use ``EXISTS`` to implement a semi-join (find rows that have matching rows in another table):
 
 .. code-block:: sql
 
@@ -344,16 +340,14 @@ This finds all employees who have at least one project assigned, without returni
 Join with User-Defined Functions
 ---------------------------------
 
-Join results from user-defined functions:
+User-defined functions can be used like tables in the ``FROM`` clause and joined with conditions in the ``WHERE`` clause:
 
 .. code-block:: sql
 
     SELECT A.col1, A.col2, B.col1, B.col2
     FROM f1(103, 'b') A, f1(103, 'b') B
     WHERE A.col1 = B.col1
 
-User-defined functions can be used like tables in the FROM clause and joined with join conditions in the WHERE clause.
-
 Important Notes
 ===============
 
@@ -362,9 +356,9 @@ Table Aliases
 
 Use aliases to:
 
-- Distinguish between multiple references to the same table
-- Shorten long table names
-- Reference columns from specific tables in multi-table joins
+- Distinguish between multiple references to the same table.
+- Shorten long table names.
+- Reference columns from specific tables in multi-table joins.
 
 .. code-block:: sql
 
@@ -375,14 +369,14 @@ Use aliases to:
 Join Conditions
 ---------------
 
-- Join conditions should be specified in the WHERE clause (for comma-separated tables) or the ON clause (for INNER JOIN)
-- Use ``AND`` to combine multiple join conditions and filters
-- Missing join conditions result in a Cartesian product (all combinations)
+- Join conditions should be specified in the ``WHERE`` clause (for comma-separated tables) or the ``ON`` clause (for ``INNER JOIN``, ``LEFT OUTER JOIN``, and ``RIGHT OUTER JOIN``).
+- Use ``AND`` to combine multiple join conditions and filters.
+- Omitting join conditions produces a Cartesian product (all combinations of rows).
 
 See Also
 ========
 
-* :doc:`sql_commands/DQL/INNER_JOIN` - INNER JOIN syntax
+* :doc:`sql_commands/DQL/JOIN` - JOIN syntax
 * :doc:`sql_commands/DQL/SELECT` - SELECT statement syntax
 * :doc:`sql_commands/DQL/WHERE` - WHERE clause filtering
 * :doc:`Subqueries` - Subqueries and correlated subqueries

docs/sphinx/source/reference/sql_commands/DQL.diagram

@@ -8,7 +8,14 @@ Diagram(
                 NonTerminal('source'),
                 Optional(
                     Sequence(
-                        Terminal('INNER JOIN'),
+                        Choice(0,
+                            Terminal('INNER JOIN'),
+                            Sequence(
+                                Choice(0, Terminal('LEFT'), Terminal('RIGHT')),
+                                Optional(Terminal('OUTER'), 'skip'),
+                                Terminal('JOIN')
+                            )
+                        ),
                         NonTerminal('source'),
                         Choice(0,
                             Sequence(

docs/sphinx/source/reference/sql_commands/DQL.rst

@@ -20,7 +20,7 @@ Syntax
 
     DQL/SELECT
     DQL/WITH
-    DQL/INNER_JOIN
+    DQL/JOIN
     DQL/WHERE
     DQL/GROUP_BY
     DQL/CASE