From ee1ec780d2dfe1e96257e67f406bb7c6586a0ee3 Mon Sep 17 00:00:00 2001
From: laurenceisla <lau.isla.c@gmail.com>
Date: Mon, 18 Oct 2021 17:34:49 -0500
Subject: [PATCH] Add nested embedding examples

---
 api.rst               | 19 +++++++++++++++++++
 releases/upcoming.rst |  4 ++++
 2 files changed, 23 insertions(+)

diff --git a/api.rst b/api.rst
index 2a56d9aad..e4255edda 100644
--- a/api.rst
+++ b/api.rst
@@ -616,6 +616,17 @@ PostgREST can also detect relationships going through join tables. Thus you can
 
   GET /actors?select=films(title,year) HTTP/1.1
 
+.. _nested_embedding:
+
+Nested Embedding
+----------------
+
+If you want to embed through join tables but need more control on the intermediate resources, you can do nested embedding. For instance, you can request the Actors, their Roles and the Films for those Roles:
+
+.. code-block:: http
+
+  GET /actors?select=roles(character,films(title,year)) HTTP/1.1
+
 Embedded Filters
 ----------------
 
@@ -651,6 +662,14 @@ Embedded resources can be aliased and filters can be applied on these aliases:
 
   GET /films?select=*,90_comps:competitions(name),91_comps:competitions(name)&90_comps.year=eq.1990&91_comps.year=eq.1991 HTTP/1.1
 
+Filters can also be applied on nested embedded resources:
+
+.. code-block:: http
+
+  GET /films?select=*,roles(*,actors(*))&roles.actors.order=last_name&roles.actors.first_name=like.*Tom* HTTP/1.1
+
+The result will show the nested actors named Tom and order them by last name. Aliases can also be used instead of the resource names to filter the nested tables.
+
 .. _embedding_partitioned_tables:
 
 Embedding Partitioned Tables
diff --git a/releases/upcoming.rst b/releases/upcoming.rst
index 060d528b0..37bc92dc0 100644
--- a/releases/upcoming.rst
+++ b/releases/upcoming.rst
@@ -21,3 +21,7 @@ Added
   + Managed to avoid a breaking change thanks to `@robertsosinski <https://github.com/robertsosinski>`_ who reported the bug that only one ``.`` character was allowed in GUC keys to the PostgreSQL team. See the `full discussion <https://www.postgresql.org/message-id/17045-6a4a9f0d1513f72b%40postgresql.org>`_.
 
   -- `@laurenceisla <https://github.com/laurenceisla>`_
+
+* Documentation improvements
+
+  + Added :ref:`nested_embedding` to the :ref:`resource_embedding` section.