From 553476d66355ef555f743295be4e62bf4eeaab3c Mon Sep 17 00:00:00 2001
From: Laurence Isla <lau.isla.c@gmail.com>
Date: Wed, 18 Sep 2024 18:37:09 -0500
Subject: [PATCH] docs: add spread embedding for one-to-many and many-to-many
 relationships

---
 docs/references/api/resource_embedding.rst | 30 ++++++++++++++++++++++
 docs/references/errors.rst                 |  4 ---
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/references/api/resource_embedding.rst b/docs/references/api/resource_embedding.rst
index 6a5ae38b34..0339edf89e 100644
--- a/docs/references/api/resource_embedding.rst
+++ b/docs/references/api/resource_embedding.rst
@@ -1189,6 +1189,36 @@ You can use this to get the columns of a join table in a many-to-many relationsh
      }
    ]
 
+On one-to-many and many-to-many relationships, spreading the embedded resource columns will aggregate them into arrays.
+
+.. code-block:: bash
+
+   # curl -g "http://localhost:3000/directors?select=title,...films(film_title:title,film_year:year)&first_name=like.Quentin*"
+
+  curl --get "http://localhost:3000/directors" \
+    -d "select=first_name,...films(film_titles:title,film_years:year)" \
+    -d "first_name=like.Quentin*"
+
+.. code-block:: json
+
+   [
+     {
+       "first_name": "Quentin",
+       "film_titles": [
+         "Pulp Fiction",
+         "Reservoir Dogs"
+       ],
+       "film_years": [
+         1994,
+         1992
+       ]
+     }
+   ]
+
+The order of the values inside the resulting array is unspecified.
+However, if more than one embedded column is selected, `it is safe to assume <https://www.postgresql.org/message-id/15950.1491843689%40sss.pgh.pa.us>`_ that all of them will return the values in the same unspecified order.
+From the previous example, we can say that "Pulp Fiction" was made in 1994 and "Reservoir Dogs" in 1992.
+
 .. note::
 
   The spread operator ``...`` is borrowed from the Javascript `spread syntax <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax>`_.
diff --git a/docs/references/errors.rst b/docs/references/errors.rst
index 30a54c267e..0ea917be43 100644
--- a/docs/references/errors.rst
+++ b/docs/references/errors.rst
@@ -241,10 +241,6 @@ Related to the HTTP request elements.
 |               |             | there is no many-to-one or one-to-one relationship between  |
 | PGRST118      |             | them.                                                       |
 +---------------+-------------+-------------------------------------------------------------+
-| .. _pgrst119: | 400         | Could not use the spread operator on the related table      |
-|               |             | because there is no many-to-one or one-to-one relationship  |
-| PGRST119      |             | between them.                                               |
-+---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst120: | 400         | An embedded resource can only be filtered using the         |
 |               |             | ``is.null`` or ``not.is.null`` :ref:`operators <operators>`.|
 | PGRST120      |             |                                                             |