From 9595ed845e4067622388dbf9bf311805bec5dae3 Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Wed, 10 May 2023 22:50:22 -0300
Subject: [PATCH] add null filtering embeds

---
 docs/references/admin.rst                  |  3 +-
 docs/references/api/resource_embedding.rst | 59 +++++++++++++++++++---
 docs/releases/v11.0.0.rst                  |  3 +-
 3 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/docs/references/admin.rst b/docs/references/admin.rst
index 2a8f01b7a..6e00eb3f9 100644
--- a/docs/references/admin.rst
+++ b/docs/references/admin.rst
@@ -104,7 +104,8 @@ You can enable tracing HTTP requests by setting :ref:`server-trace-header`. Spec
 
   .. code-tab:: http
 
-    GET /users
+    GET /users HTTP/1.1
+
     X-Request-Id: 123
 
   .. code-tab:: bash Curl
diff --git a/docs/references/api/resource_embedding.rst b/docs/references/api/resource_embedding.rst
index ed44c47cb..456e03dbf 100644
--- a/docs/references/api/resource_embedding.rst
+++ b/docs/references/api/resource_embedding.rst
@@ -481,24 +481,71 @@ In order to filter the top level rows you need to add ``!inner`` to the embedded
     }
   ]
 
-.. _empty_embed_filter:
+.. _null_embed:
 
-Empty Embed Filter
-~~~~~~~~~~~~~~~~~~
+Null filtering on Embedded Resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you want to filter the films by actors but don't want to include them in the response, empty the embedded columns.
+Null filtering on the embedded resources can behave the same as ``!inner``. While providing more flexibility.
+
+For example, doing ``actors=not.is.null`` returns the same result as ``actors!inner(*)``:
 
 .. tabs::
 
   .. code-tab:: http
 
-    GET /films?select=title,actors!inner()&actors.first_name=eq.Jehanne HTTP/1.1
+    GET /films?select=title,actors(*)&actors=not.is.null HTTP/1.1
 
   .. code-tab:: bash Curl
 
-    curl "http://localhost:3000/films?select=title,actors!inner()&actors.first_name=eq.Jehanne"
+    curl "http://localhost:3000/films?select=title,actors(*)&actors=not.is.null"
+
+The ``is.null`` filter can be used in embedded resources to perform an anti-join. To get all the films that do not have any nominations:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET /films?select=title,nominations()&nominations=is.null HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/films?select=title,nominations()&nominations=is.null"
+
+
+Both ``is.null`` and ``not.is.null`` can be included inside the `or` operator. For instance, to get the films that have no actors **or** directors registered yet:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET /films?select=title,actors(*),directors(*)&or=(actors.is.null,directors.is.null) HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/films?select=title,actors(*),directors(*)&or=(actors.is.null,directors.is.null)"
+
+.. _empty_embed:
+
+Empty Embed
+~~~~~~~~~~~
+
+You can leave an embedded resource empty, this helps with filtering in some cases.
+
+To filter the films by actors but not include them:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET /films?select=title,actors()&actors.first_name=eq.Jehanne&actors=not.is.null HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/films?select=title,actors()&actors.first_name=eq.Jehanne&actors=not.is.null"
 
 .. code-block:: json
+
   [
     {
       "title": "The Haunted Castle",
diff --git a/docs/releases/v11.0.0.rst b/docs/releases/v11.0.0.rst
index 5223369e1..7eba9688a 100644
--- a/docs/releases/v11.0.0.rst
+++ b/docs/releases/v11.0.0.rst
@@ -13,8 +13,9 @@ Horizontal Filtering
 Resource Embedding
 ~~~~~~~~~~~~~~~~~~
 
-- New :ref:`empty_embed_filter`.
 - New :ref:`top_level_order`.
+- New :ref:`null_embed`.
+- New :ref:`empty_embed`.
 
 OpenAPI
 ~~~~~~~