docs: add spread embedding for one-to-many and many-to-many relations…

…hips

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>`_.

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      |             |                                                             |