Skip to content

Commit

Permalink
docs: add spread embedding for one-to-many and many-to-many relations…
Browse files Browse the repository at this point in the history
…hips
  • Loading branch information
laurenceisla committed Sep 18, 2024
1 parent 650cc3e commit b3e5483
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 4 deletions.
30 changes: 30 additions & 0 deletions docs/references/api/resource_embedding.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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>`_.
4 changes: 0 additions & 4 deletions docs/references/errors.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 | | |
Expand Down

0 comments on commit b3e5483

Please sign in to comment.