From a659b0005a5d1c40d0f39ea87f584750f1f2d64c Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Thu, 15 May 2025 15:50:31 -0500
Subject: [PATCH] docs: clarify spread join table

---
 docs/references/api/resource_embedding.rst | 55 +++++++++++-----------
 1 file changed, 28 insertions(+), 27 deletions(-)

diff --git a/docs/references/api/resource_embedding.rst b/docs/references/api/resource_embedding.rst
index 1593eaef4..e9ecb531f 100644
--- a/docs/references/api/resource_embedding.rst
+++ b/docs/references/api/resource_embedding.rst
@@ -1238,33 +1238,6 @@ You can order the correlated arrays explicitly. For example, to order by the fil
      }
    ]
 
-Spread a join table
--------------------
-
-Spread can be used to lift the columns of a join table in a :ref:`many-to-many <many-to-many>` relationship. For instance, to lift the ``roles`` join table columns into ``actors``:
-
-.. code-block:: bash
-
-  curl --get "http://localhost:3000/films" \
-    -d "select=title,actors:roles(character,...actors(first_name,last_name))" \
-    -d "title=like.*Lighthouse*"
-
-.. code-block:: json
-
-   [
-     {
-       "title": "The Lighthouse",
-       "actors": [
-          {
-            "character": "Thomas Wake",
-            "first_name": "Willem",
-            "last_name": "Dafoe"
-          }
-       ]
-     }
-   ]
-
-
 Multiple Spreads
 ----------------
 
@@ -1307,3 +1280,31 @@ Note that:
 - All the ``film_*`` arrays are correlated—"Reservoir Dogs" premiered in 1992, its runtime is 1:39:00 and it has the following characters: ``[ "Mr. Pink", "Mr. White" ]``.
 - The ``film_*`` arrays are ordered by ``year`` (due to ``films.order=year``).
 - The bottom level array ``film_characters`` is ordered (due to ``films.roles.order=character``).
+
+Spread a join table
+-------------------
+
+Spread can be used to move the columns of a join table in a :ref:`many-to-many <many-to-many>` to the top object. For instance, to get the ``character`` column of the ``roles`` join table into ``actors``:
+
+.. code-block:: bash
+
+  curl --get "http://localhost:3000/films" \
+    -d "select=title,actors:roles(character,...actors(first_name,last_name))" \
+    -d "title=like.*Lighthouse*"
+
+.. code-block:: json
+
+   [
+     {
+       "title": "The Lighthouse",
+       "actors": [
+          {
+            "character": "Thomas Wake",
+            "first_name": "Willem",
+            "last_name": "Dafoe"
+          }
+       ]
+     }
+   ]
+
+