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

…hips

docs/references/api/aggregate_functions.rst

@@ -286,3 +286,5 @@ The result will be the same as if the aggregations were applied to columns from
       "min": "2016-02-11"
     }
   ]
+
+Similarly, this is also possible for :ref:`one-to-many and many-to-many spread resources <spread_to_many_embed>`.

docs/references/api/resource_embedding.rst

@@ -1150,7 +1150,17 @@ For example, to arrange the films in descending order using the director's last
 Spread embedded resource
 ========================
 
-On many-to-one and one-to-one relationships, you can "spread" the embedded resource. That is, remove the surrounding JSON object for the embedded resource columns.
+The ``...`` operator lets you "spread" an embedded resource.
+That is, it removes the surrounding JSON object for the embedded resource columns.
+
+.. note::
+
+  The spread operator ``...`` is borrowed from the Javascript `spread syntax <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax>`_.
+
+Spread One-To-One and Many-To-One relationships
+-----------------------------------------------
+
+Take the following example:
 
 .. code-block:: bash
 
@@ -1196,6 +1206,40 @@ You can use this to get the columns of a join table in a many-to-many relationsh
      }
    ]
 
-.. note::
+.. _spread_to_many_embed:
 
-  The spread operator ``...`` is borrowed from the Javascript `spread syntax <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax>`_.
+Spread One-To-Many and Many-To-Many relationships
+-------------------------------------------------
+
+For these relationships, the spread embedded resource columns will be aggregated into arrays.
+
+.. code-block:: bash
+
+   # curl -g "http://localhost:3000/directors?select=first_name,...films(film_titles:title,film_years: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.
+
+It is expected to get ``null`` values in the resulting array.
+You can exclude them with :ref:`stripped_nulls`.

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