From 9b48f86131b7d4db56e72e72f39ff491d173e681 Mon Sep 17 00:00:00 2001 From: rikinsk Date: Tue, 10 Dec 2019 14:57:03 +0530 Subject: [PATCH 1/5] add boolean expressions syntactic sugar notes --- .../api-reference/graphql-api/query.rst | 10 +++ docs/graphql/manual/queries/query-filters.rst | 61 +++++++++++++++++++ 2 files changed, 71 insertions(+) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index 7ec8162a6c15f..b1124159d5fb1 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -309,6 +309,16 @@ AndExp _and: [BoolExp_] } +or + +.. parsed-literal:: + + { + BoolExp_, + BoolExp_, + ... + } + OrExp ##### diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 4297d1647bc6e..3db510b0b4ac3 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -866,6 +866,28 @@ Fetch a list of articles published in a specific time-frame (for example: in yea } } +.. 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" } + } + Example: _or ^^^^^^^^^^^^^ Fetch a list of articles rated more than 4 or published after "01/01/2018": @@ -921,6 +943,45 @@ 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. Passing an object to it will result in the + behaviour of the ``_and`` operator. + + **For example:** + + .. code-block:: graphql + + { + _or: { + rating: { _gte: 4 }, + published_on: { _gte: "2018-01-01" } + } + } + + # will be resolved 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" } } + ] + ] + } + .. _nested_filter: Filter nested objects From 782122db4ed314bbbe71a49fa0cb8960211f8b8a Mon Sep 17 00:00:00 2001 From: rikinsk Date: Tue, 10 Dec 2019 15:21:31 +0530 Subject: [PATCH 2/5] add link to graphql spec --- docs/graphql/manual/queries/query-filters.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index 3db510b0b4ac3..33ac185187ca0 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -947,7 +947,8 @@ 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. Passing an object to it will result in the - behaviour of the ``_and`` operator. + behaviour of the ``_and`` operator due to the way `GraphQL list input coercion `_ + behaves. **For example:** @@ -960,7 +961,7 @@ Fetch a list of articles rated more than 4 or published after "01/01/2018": } } - # will be resolved to: + # will be coerced to: { _or: [ From d2a8ef65efe1c6c257c893223f6d6ae6456c9131 Mon Sep 17 00:00:00 2001 From: rikinsk Date: Tue, 17 Dec 2019 12:56:21 +0530 Subject: [PATCH 3/5] move syntactic sugar notes to reference --- .../api-reference/graphql-api/query.rst | 66 +++++++++++++++++-- docs/graphql/manual/queries/query-filters.rst | 60 ++--------------- 2 files changed, 65 insertions(+), 61 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index b1124159d5fb1..7ffc3d7aaee6e 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,16 +311,30 @@ AndExp _and: [BoolExp_] } -or +.. admonition:: Syntactic sugar -.. parsed-literal:: + You can simplify an ``_and`` expression by passing the sub-expressions separated by a ``,`` + + **For example:** + + .. code-block:: graphql { - BoolExp_, - BoolExp_, - ... + _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 ##### @@ -328,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 `_ + 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 33ac185187ca0..f6d5a93d29be3 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -866,27 +866,9 @@ Fetch a list of articles published in a specific time-frame (for example: in yea } } -.. 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: +.. note:: - { - rating: { _gte: 4 }, - published_on: { _gte: "2018-01-01" } - } + It is possible to simplify the ``_and`` expression. See the :ref:`API reference ` for more details. Example: _or ^^^^^^^^^^^^^ @@ -946,42 +928,8 @@ 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. Passing an object to it will result in the - behaviour of the ``_and`` operator due to the way `GraphQL list input coercion `_ - 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" } } - ] - ] - } + The ``_or`` operator expects an array of expressions as input. See the :ref:`API reference ` for details on + the behaviour if an object is passed as input .. _nested_filter: From fab6a9e9f537113425ba6f0ed9f07ac89769d8ec Mon Sep 17 00:00:00 2001 From: rikinsk Date: Tue, 17 Dec 2019 13:01:01 +0530 Subject: [PATCH 4/5] fix typo --- docs/graphql/manual/api-reference/graphql-api/query.rst | 2 +- 1 file changed, 1 insertion(+), 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 7ffc3d7aaee6e..c9b91d3289203 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -333,7 +333,7 @@ AndExp published_on: { _gte: "2018-01-01" } } -.. _orExp: +.. _OrExp: OrExp ##### From adc2b6ca0f50e91a209346f7303ea57de0810335 Mon Sep 17 00:00:00 2001 From: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> Date: Tue, 17 Dec 2019 16:13:39 +0530 Subject: [PATCH 5/5] Apply suggestions from code review Co-Authored-By: Marion Schleifer --- docs/graphql/manual/api-reference/graphql-api/query.rst | 2 +- docs/graphql/manual/queries/query-filters.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst index c9b91d3289203..5852dadf37ab1 100644 --- a/docs/graphql/manual/api-reference/graphql-api/query.rst +++ b/docs/graphql/manual/api-reference/graphql-api/query.rst @@ -313,7 +313,7 @@ AndExp .. admonition:: Syntactic sugar - You can simplify an ``_and`` expression by passing the sub-expressions separated by a ``,`` + You can simplify an ``_and`` expression by passing the sub-expressions separated by a ``,``. **For example:** diff --git a/docs/graphql/manual/queries/query-filters.rst b/docs/graphql/manual/queries/query-filters.rst index a6d74832926a9..f58dc93b0a854 100644 --- a/docs/graphql/manual/queries/query-filters.rst +++ b/docs/graphql/manual/queries/query-filters.rst @@ -1086,7 +1086,7 @@ 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 ` for details on - the behaviour if an object is passed as input + the behaviour if an object is passed as input. .. _nested_filter: