diff --git a/docs/graphql/manual/api-reference/mutation.rst b/docs/graphql/manual/api-reference/mutation.rst index 0e4ef70ec4f8a..366119529abe5 100644 --- a/docs/graphql/manual/api-reference/mutation.rst +++ b/docs/graphql/manual/api-reference/mutation.rst @@ -323,8 +323,6 @@ E.g.: where: BoolExp_ -.. _BoolExp: - BoolExp ******* diff --git a/docs/graphql/manual/api-reference/query.rst b/docs/graphql/manual/api-reference/query.rst index 3aa79b2e7432f..d79718e5a5a66 100644 --- a/docs/graphql/manual/api-reference/query.rst +++ b/docs/graphql/manual/api-reference/query.rst @@ -63,11 +63,12 @@ Query/Subscription syntax Syntax definitions ------------------ -.. _Object: - Object ^^^^^^ +Simple Object :- +**************** + .. code-block:: none object-name { @@ -76,6 +77,7 @@ Object .. nested object1 nested object2 + aggregate nested object1 .. } @@ -84,14 +86,139 @@ E.g. .. code-block:: graphql author { - id # scalar field - name # scalar field - article { # nested object + id # scalar field + name # scalar field + article { # nested object title } + article_aggregate { # aggregate nested object + aggregate { + count + } + nodes { + title + } + } } -.. _Argument: +Aggregate Object :- +******************* + +.. code-block:: none + + object-name_aggregate { + aggregate { + count + sum { + field + .. + } + avg { + field + .. + } + stddev { + field + .. + } + stddev_samp { + field + .. + } + stddev_pop { + field + .. + } + variance { + field + .. + } + var_samp { + field + .. + } + var_pop { + field + .. + } + max { + field + .. + } + min { + field + .. + } + nodes { + field1 + field2 + .. + nested object1 + nested object2 + aggregate nested object1 + .. + } + } + +(For more details on aggregate functions, refer to `Postgres docs `__.) + +E.g. + +.. code-block:: graphql + + author_aggregate { + aggregate { + count # total count + sum { + id # sum aggregate on id + } + avg { + id # avg aggregate on id + } + stddev { + id # stddev aggregate on id + } + stddev_samp { + id # stddev_samp aggregate on id + } + stddev_pop { + id # stddev_pop aggregate on id + } + variance { + id # variance aggregate on id + } + var_samp { + id # var_samp aggregate on id + } + var_pop { + id # var_pop aggregate on id + } + max { + id # max aggregate on id + } + min { + id # min aggregate on id + } + } + + nodes { # objects + id # scalar field + name # scalar field + + article { # nested object + title + } + + article_aggregate{ # aggregate nested object + aggregate { + count + } + nodes { + title + } + } + } + } Argument ^^^^^^^^ @@ -109,8 +236,6 @@ WhereExp where: BoolExp_ -.. _BoolExp: - BoolExp """"""" @@ -118,8 +243,6 @@ BoolExp AndExp_ | OrExp_ | NotExp_ | ColumnExp_ -.. _AndExp: - AndExp ###### @@ -129,8 +252,6 @@ AndExp _and: [BoolExp_] } -.. _OrExp: - OrExp ##### @@ -140,8 +261,6 @@ OrExp _or: [BoolExp_] } -.. _NotExp: - NotExp ###### @@ -193,7 +312,7 @@ JSONB operators: * - ``_has_keys_all`` - ``?&`` -(For more details on what these operators do, refer to `Postgres docs `_.) +(For more details on what these operators do, refer to `Postgres docs `__.) Text related operators : @@ -231,8 +350,6 @@ or order_by: [{id: desc}, {author: {id: asc}}] -.. _TableOrderBy: - TableOrderBy ************ @@ -262,8 +379,6 @@ Order by type for "article" table: author: author_order_by } -.. _OrderByEnum: - OrderByEnum *********** diff --git a/docs/graphql/manual/event-triggers/payload.rst b/docs/graphql/manual/event-triggers/payload.rst index 6641c1284a71f..6ea323bb085a7 100644 --- a/docs/graphql/manual/event-triggers/payload.rst +++ b/docs/graphql/manual/event-triggers/payload.rst @@ -115,8 +115,6 @@ JSON payload Syntax definitions ------------------ -.. _Object: - Object ^^^^^^ @@ -129,8 +127,6 @@ Object } -.. _OpName: - OpName ^^^^^^ diff --git a/docs/graphql/manual/queries/aggregation-queries.rst b/docs/graphql/manual/queries/aggregation-queries.rst new file mode 100644 index 0000000000000..1bee01e4f4886 --- /dev/null +++ b/docs/graphql/manual/queries/aggregation-queries.rst @@ -0,0 +1,171 @@ +Aggregation queries +=================== + +You can fetch aggregations on columns along with nodes using an aggregation query. +Available aggregation queries are ``count``, ``sum``, ``avg``, ``max`` and ``min``. + +For example, fetch a list of articles with aggregated data: + +.. graphiql:: + :view_only: + :query: + query { + article_aggregate { + aggregate { + count + sum { + rating + } + avg { + rating + } + max { + rating + } + } + nodes { + id + title + rating + } + } + } + :response: + { + "data": { + "article_aggregate": { + "aggregate": { + "count": 10, + "sum": { + "rating": 26 + }, + "avg": { + "rating": 2.6 + }, + "max": { + "rating": 4 + } + }, + "nodes": [ + { + "id": 1, + "title": "sit amet", + "rating": 1 + }, + { + "id": 2, + "title": "a nibh", + "rating": 3 + }, + { + "id": 3, + "title": "amet justo morbi", + "rating": 4 + }, + { + "id": 4, + "title": "vestibulum ac est", + "rating": 2 + }, + { + "id": 5, + "title": "ut blandit", + "rating": 2 + }, + { + "id": 6, + "title": "sapien ut", + "rating": 1 + }, + { + "id": 7, + "title": "nisl duis ac", + "rating": 4 + }, + { + "id": 8, + "title": "donec semper sapien", + "rating": 3 + }, + { + "id": 9, + "title": "sit amet", + "rating": 3 + }, + { + "id": 10, + "title": "dui proin leo", + "rating": 3 + } + ] + } + } + } + +Fetch aggregations data on nested objects +----------------------------------------- +The following is an example of a nested object query with aggregations on the **array relationship** between author and +articles. + +Fetch an author whose id is ``1`` and a nested list of articles with aggregated data: + +.. graphiql:: + :view_only: + :query: + query { + author (where: {id: {_eq: 1}}) { + id + name + articles_aggregate { + aggregate { + count + avg { + rating + } + max { + rating + } + } + nodes { + id + title + rating + } + } + } + } + :response: + { + "data": { + "author": [ + { + "id": 1, + "name": "Justin", + "articles_aggregate": { + "aggregate": { + "count": 2, + "avg": { + "rating": 2.5 + }, + "max": { + "rating": 4 + } + }, + "nodes": [ + { + "id": 15, + "title": "vel dapibus at", + "rating": 4 + }, + { + "id": 16, + "title": "sem duis aliquam", + "rating": 1 + } + ] + } + } + ] + } + } + diff --git a/docs/graphql/manual/queries/aggregations.rst b/docs/graphql/manual/queries/derived-data.rst similarity index 85% rename from docs/graphql/manual/queries/aggregations.rst rename to docs/graphql/manual/queries/derived-data.rst index d6abefdc11ed0..42caf602353ba 100644 --- a/docs/graphql/manual/queries/aggregations.rst +++ b/docs/graphql/manual/queries/derived-data.rst @@ -1,16 +1,16 @@ -.. meta:: - :keywords: computed fields, derived data, aggregations - Derived data in queries ======================= -GraphQL’s "select" query language is designed to be simple yet powerful. But there are still certain -queries that you cannot express with a GraphQL query. For example, getting the average rating of articles by an -author. + +GraphQL’s "select" query language is designed to be simple yet powerful. But there are certain +queries that you cannot express with a simple GraphQL query. For example, getting data from a custom join. To express complex queries for derived data like aggregations or custom joins etc., use SQL, which is designed for this -purpose. If you can express your aggregation query in SQL, define a view with it and then use the newly created +purpose. If you can express your query in SQL, define a view with it and then use the newly created type in the GraphQL query. +.. note:: + Also see :doc:`aggregation-queries` to fetch aggregation data without creating a view. + For example, let’s see how to fetch the average article rating for each author in our author/article schema: 1) Create a view @@ -90,4 +90,4 @@ Fetch a list of authors along with their average article rating: } } -This example can be easily extended to cover any use-case involving an SQL aggregate function that you may want to use. +This example can be easily extended to cover any use-case involving a complicated SQL query that you may want to use. diff --git a/docs/graphql/manual/queries/index.rst b/docs/graphql/manual/queries/index.rst index 718d03a80cee8..3e8c889db0886 100644 --- a/docs/graphql/manual/queries/index.rst +++ b/docs/graphql/manual/queries/index.rst @@ -32,10 +32,11 @@ based on a typical author/article schema for reference. simple-object-queries nested-object-queries + aggregation-queries query-filters sorting pagination Using multiple arguments multiple-queries - aggregations + derived-data control-access diff --git a/docs/graphql/manual/queries/nested-object-queries.rst b/docs/graphql/manual/queries/nested-object-queries.rst index b0e2ca71c684f..7ac8175da56dc 100644 --- a/docs/graphql/manual/queries/nested-object-queries.rst +++ b/docs/graphql/manual/queries/nested-object-queries.rst @@ -4,6 +4,55 @@ Nested object queries You can use the object (one-to-one) or array (one-to-many) :doc:`relationships <../schema/relationships/index>` defined in your schema to make a nested query i.e. fetch data for a type along with data from a nested or related type. + +Query using an object relationship +---------------------------------- +The following is an example of a nested object query using the ``object relationship`` between an article and an +author. + +Fetch a list of articles and the name of each article’s author: + +.. graphiql:: + :view_only: + :query: + query { + article { + id + title + author { + name + } + } + } + :response: + { + "data": { + "article": [ + { + "id": 1, + "title": "sit amet", + "author": { + "name": "Anjela" + } + }, + { + "id": 2, + "title": "a nibh", + "author": { + "name": "Beltran" + } + }, + { + "id": 3, + "title": "amet justo morbi", + "author": { + "name": "Anjela" + } + } + ] + } + } + Query using an array relationship --------------------------------- The following is an example of a nested object query using the ``array relationship`` between an author and @@ -78,55 +127,75 @@ Fetch a list of authors and a nested list of each author’s articles: } } -Query using an object relationship ----------------------------------- -The following is an example of a nested object query using the ``object relationship`` between an article and an -author. -Fetch a list of articles and the name of each article’s author: +.. note:: + + The name of the nested object is the same as the name of the object or array relationship configured in the + console. + +Query with aggregations on an array relationship +------------------------------------------------ +The following is an example of a nested object query with aggregations on array relationship between author and +articles. + +Fetch an author whose id is ``1`` and a nested list of articles with aggregated data: .. graphiql:: :view_only: :query: query { - article { + author (where: {id: {_eq: 1}}) { id - title - author { - name + name + articles_aggregate { + aggregate { + count + avg { + rating + } + max { + rating + } + } + nodes { + id + title + rating + } } } } :response: { "data": { - "article": [ + "author": [ { "id": 1, - "title": "sit amet", - "author": { - "name": "Anjela" - } - }, - { - "id": 2, - "title": "a nibh", - "author": { - "name": "Beltran" - } - }, - { - "id": 3, - "title": "amet justo morbi", - "author": { - "name": "Anjela" + "name": "Justin", + "articles_aggregate": { + "aggregate": { + "count": 2, + "avg": { + "rating": 2.5 + }, + "max": { + "rating": 4 + } + }, + "nodes": [ + { + "id": 15, + "title": "vel dapibus at", + "rating": 4 + }, + { + "id": 16, + "title": "sem duis aliquam", + "rating": 1 + } + ] } } ] } } - -.. note:: - - The name of the nested object is the same as the name of the object or array relationship configured in the - console. diff --git a/docs/graphql/manual/subscriptions/use-cases.rst b/docs/graphql/manual/subscriptions/use-cases.rst index f70d88a9dbb3e..90d178dd872da 100644 --- a/docs/graphql/manual/subscriptions/use-cases.rst +++ b/docs/graphql/manual/subscriptions/use-cases.rst @@ -157,7 +157,7 @@ Subscribe to latest value of some derived data ---------------------------------------------- In case you are interested in the latest value of some derived data, you can :doc:`create a view to query the derived -data <../queries/aggregations>` and then use subscriptions to fetch the derived value and get its latest value +data <../queries/derived-data>` and then use subscriptions to fetch the derived value and get its latest value whenever it updates. Example: A poll dashboard