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