From deeae45b9e7e867618fb8a330fd01c8fcf4f2f26 Mon Sep 17 00:00:00 2001
From: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
Date: Tue, 17 Dec 2019 19:52:39 +0530
Subject: [PATCH] add boolean expressions syntactic sugar notes in docs (#3510)

---
 .../api-reference/graphql-api/query.rst       | 66 +++++++++++++++++++
 docs/graphql/manual/queries/query-filters.rst | 11 +++-
 2 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst
index 7ec8162a..5852dadf 100644
--- a/docs/graphql/manual/api-reference/graphql-api/query.rst
+++ b/docs/graphql/manual/api-reference/graphql-api/query.rst
@@ -300,6 +300,8 @@ BoolExp
 
    AndExp_ | OrExp_ | NotExp_ | TrueExp_ | ColumnExp_
 
+.. _AndExp:
+
 AndExp
 ######
 
@@ -309,6 +311,30 @@ AndExp
       _and: [BoolExp_]
     }
 
+.. admonition:: Syntactic sugar
+
+  You can simplify an ``_and`` expression by passing the sub-expressions separated by a ``,``.
+
+  **For example:**
+
+  .. code-block:: graphql
+
+    {
+      _and: [
+        { rating: { _gte: 4 } },
+        { published_on: { _gte: "2018-01-01" } }
+      ]
+    }
+
+    # can be simplified to:
+
+    {
+      rating: { _gte: 4 },
+      published_on: { _gte: "2018-01-01" }
+    }
+
+.. _OrExp:
+
 OrExp
 #####
 
@@ -318,6 +344,46 @@ OrExp
       _or: [BoolExp_]
     }
 
+.. note::
+
+  The ``_or`` operator expects an array of expressions as input. Passing an object to it will result in the
+  behaviour of the ``_and`` operator due to the way `GraphQL list input coercion <https://graphql.github.io/graphql-spec/June2018/#sec-Type-System.List>`_
+  behaves.
+
+  **For example:**
+
+  .. code-block:: graphql
+
+    {
+      _or: {
+       rating: { _gte: 4 },
+       published_on: { _gte: "2018-01-01" }
+      }
+    }
+
+    # will be coerced to:
+
+    {
+      _or: [
+        {
+          rating: { _gte: 4 },
+          published_on: { _gte: "2018-01-01" }
+        }
+      ]
+    }
+
+    # which is equivalent to:
+
+    {
+      _or: [
+        _and: [
+          { rating: { _gte: 4 } },
+          { published_on: { _gte: "2018-01-01" } }
+        ]
+      ]
+    }
+
+
 NotExp
 ######
 
diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst
index a8557158..f58dc93b 100644
--- a/docs/graphql/manual/queries/query-filters.rst
+++ b/docs/graphql/manual/queries/query-filters.rst
@@ -1024,6 +1024,10 @@ Fetch a list of articles published in a specific time-frame (for example: in yea
       }
     }
 
+.. note::
+
+  It is possible to simplify the ``_and`` expression. See the :ref:`API reference <AndExp>` for more details.
+
 **Example:  _or**
 
 Fetch a list of articles rated more than 4 or published after "01/01/2018":
@@ -1079,6 +1083,11 @@ Fetch a list of articles rated more than 4 or published after "01/01/2018":
       }
     }
 
+.. note::
+
+  The ``_or`` operator expects an array of expressions as input. See the :ref:`API reference <OrExp>` for details on
+  the behaviour if an object is passed as input.
+
 .. _nested_filter:
 
 Filter nested objects
@@ -1682,4 +1691,4 @@ Evaluation of **null** values in comparision expressions
 If in any comparision expression a ``null`` (or ``undefined``) value is passed, the expression currently gets
 reduced to ``{}`` (:ref:`TRUE expression <true_expression>`)
 
-**For example**, the expression ``{ where: { _eq: null } }`` will be reduced to ``{ where: {} }``
\ No newline at end of file
+**For example**, the expression ``{ where: { _eq: null } }`` will be reduced to ``{ where: {} }``