docs: add missing examples to API docs (close #4745) (#4844)

docs/graphql/manual/api-reference/graphql-api/mutation.rst

@@ -55,7 +55,7 @@ API Reference - Mutation
      - ConflictClause_
      - Converts *insert* to *upsert* by handling conflict
 
-**E.g. INSERT**:
+**Example: Insert**
 
 .. code-block:: graphql
 
@@ -76,7 +76,7 @@ API Reference - Mutation
       }
     }
 
-**E.g. UPSERT**:
+**Example: Upsert**
 
 .. code-block:: graphql
 
@@ -140,7 +140,7 @@ API Reference - Mutation
      - ConflictClause_
      - Converts *insert* to *upsert* by handling conflict
 
-**E.g. INSERT ONE**:
+**Example: Insert One**
 
 .. code-block:: graphql
 
@@ -220,7 +220,7 @@ API Reference - Mutation
      - deleteAtPathArgExp_
      - Element at path to be deleted in the value of JSONB columns in the table
 
-**E.g. UPDATE BY PK**:
+**Example: Update by PK**
 
 .. code-block:: graphql
 
@@ -303,7 +303,7 @@ API Reference - Mutation
      - MutationResponse_
      - Object to be returned after mutation succeeds
 
-**E.g. UPDATE**:
+**Example: Update**
 
 .. code-block:: graphql
 
@@ -347,7 +347,7 @@ API Reference - Mutation
      - Value
      - Name of the auto-generated delete mutation field, e.g. *delete_author_by_pk*
 
-**E.g. DELETE BY PK**:
+**Example: Delete by PK**
 
 .. code-block:: graphql
 
@@ -398,7 +398,7 @@ API Reference - Mutation
      - MutationResponse_
      - Object to be returned after mutation succeeds
 
-**E.g. DELETE**:
+**Example: Delete**
 
 .. code-block:: graphql
 
@@ -436,7 +436,7 @@ Mutation response
       }
     }
 
-E.g.:
+**Example**
 
 .. code-block:: graphql
 
@@ -473,7 +473,7 @@ E.g.:
     ]
     # no nested objects
 
-E.g.:
+**Example**
 
 .. code-block:: graphql
 
@@ -512,7 +512,7 @@ E.g.:
     }
 
 
-E.g.:
+**Example**
 
 .. code-block:: graphql
 
@@ -543,7 +543,7 @@ table has *update* permissions defined.
       where: table_bool_exp
     }
 
-E.g.:
+**Example**
 
 .. code-block:: graphql
 
@@ -567,7 +567,7 @@ The ``pk_columns`` argument is used to identify an object by its primary key col
       column-2: value-2
     }
 
-E.g.:
+**Example**
 
 .. code-block:: graphql
 
@@ -585,6 +585,14 @@ E.g.:
 
     where: BoolExp_
 
+**Example**
+
+.. code-block:: graphql
+
+  where: {
+    rating: {_eq: 5}
+  }
+
 BoolExp
 *******
 
@@ -602,6 +610,15 @@ AndExp
     }
 
 
+**Example**
+
+.. code-block:: graphql
+
+  _and: [
+    {rating: {_gt: 5}}, 
+    {updated_at: {_gt: "2019-01-01"}}
+  ]
+
 OrExp
 #####
 
@@ -611,6 +628,15 @@ OrExp
       _or: [BoolExp_]
     }
 
+**Example**
+
+.. code-block:: graphql
+
+  _or: [
+    {rating: {_is_null: true}}, 
+    {rating: {_lt: 4}}
+  ]
+
 NotExp
 ######
 
@@ -620,6 +646,13 @@ NotExp
       _not: BoolExp_
     }
 
+**Example**
+
+.. code-block:: graphql
+
+  _not: {
+    title: {_eq: ""}
+  }
 
 TrueExp
 #######
@@ -628,6 +661,16 @@ TrueExp
 
     {}
 
+**Example**
+
+.. code-block:: graphql
+
+  author(where: {articles: {}})
+
+.. note::
+
+  ``{}`` evaluates to true whenever an object exists (even if it's ``null``).
+
 ColumnExp
 #########
 
@@ -637,6 +680,12 @@ ColumnExp
       field-name: {Operator_: Value }
     }
 
+**Example**
+
+.. code-block:: graphql
+
+  {rating: {_eq: 5}}
+
 Operator
 ########
 
@@ -712,7 +761,7 @@ Operator
      ..
    }
 
-E.g.
+**Example**
 
 .. code-block:: json
 
@@ -734,7 +783,7 @@ E.g.
      ..
    }
 
-E.g.
+**Example**
 
 .. code-block:: json
 

docs/graphql/manual/api-reference/graphql-api/query.rst

@@ -43,7 +43,7 @@ API Reference - Query / Subscription
      - Argument_
      - One or more of filter criteria, instructions for sort order or pagination
 
-**E.g. QUERY**:
+**Example: Query**
 
 .. code-block:: graphql
 
@@ -54,7 +54,7 @@ API Reference - Query / Subscription
       }
     }
 
-**E.g. SUBSCRIPTION**:
+**Example: Subscription**
 
 .. code-block:: graphql
 
@@ -98,7 +98,7 @@ API Reference - Query / Subscription
      - Value
      - Name of the auto-generated query field, e.g. *article_by_pk*
 
-**E.g. QUERY BY PK**:
+**Example: Query by PK**
 
 .. code-block:: graphql
 
@@ -109,7 +109,7 @@ API Reference - Query / Subscription
       }
     }
 
-**E.g. SUBSCRIPTION BY PK**:
+**Example: Subscription by PK**
 
 .. code-block:: graphql
 
@@ -160,7 +160,7 @@ Simple object
      - Value
      - ``path`` argument of ``json``/``jsonb`` follows simple `JSONPath specification <https://github.com/json-path/JsonPath>`_. However, prefix symbol ``$.`` is optional.
 
-E.g.
+*Example*
 
 .. code-block:: graphql
 
@@ -254,7 +254,7 @@ Aggregate object
 
 (For more details on aggregate functions, refer to the `Postgres docs <https://www.postgresql.org/docs/current/functions-aggregate.html#FUNCTIONS-AGGREGATE-STATISTICS-TABLE>`__).
 
-E.g.
+*Example*
 
 .. code-block:: graphql
 
@@ -329,6 +329,17 @@ DistinctOnExp
 
    distinct_on: [ TableSelectColumnEnum_ ]
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(distinct_on: title) {
+      title
+      content
+    }
+  }
+
 TableSelectColumnEnum
 """""""""""""""""""""
 
@@ -353,6 +364,19 @@ WhereExp
 
    where: BoolExp_
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    author(where: {rating: {_gt: 4}}) {
+      name
+      articles {
+        title
+      }
+    }
+  }
+
 BoolExp
 """""""
 
@@ -371,6 +395,17 @@ AndExp
       _and: [BoolExp_]
     }
     
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(where: {_and: [{rating: {_gt: 4}}, {published_on: {_gt: "2018-01-01"}}]}) {
+      title
+      content
+    }
+  }
+
 .. admonition:: Syntactic sugar
 
   You can simplify an ``_and`` expression by passing the sub-expressions separated by a ``,``.
@@ -404,13 +439,24 @@ OrExp
       _or: [BoolExp_]
     }
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(where: {_or: [{rating: {_gt: 4}}, {is_published: {_eq: true}}]}) {
+      title
+      content
+    }
+  }
+
 .. 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:**
+  *Example:*
 
   .. code-block:: graphql
 
@@ -453,6 +499,17 @@ NotExp
       _not: BoolExp_
     }
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(where: {_not: {title: {_eq: ""}}} ) {
+      title
+      content
+    }
+  }
+
 TrueExp
 #######
 
@@ -460,6 +517,20 @@ TrueExp
 
     {}
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    author(where: {articles: {}}) {
+      name
+    }
+  }
+
+.. note::
+
+  ``{}`` evaluates to true whenever an object exists (even if it's ``null``).
+
 ColumnExp
 #########
 
@@ -469,6 +540,17 @@ ColumnExp
       field-name : {Operator_: Value }
     }
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(where: {title: {_eq: "GraphQL Tutorial"}}) {
+      title
+      content
+    }
+  }
+
 .. _Operator:
 
 Operator
@@ -646,6 +728,32 @@ CastExp
 
     {type-name: {Operator_: Value}}
 
+*Example*
+
+.. code-block:: graphql
+
+  query MyQuery($coordinate: geography!) {
+    postgis_test_table(
+      where: {
+        geometry_column: {
+          _cast: {
+            geography: { _st_d_within: { distance: 1000000, from: $coordinate } }
+          }
+        }
+      }
+    ) {
+      id
+    }
+  }
+  
+  Variables:
+  {
+    "coordinate": {
+      "type": "Point",
+      "coordinates": [ 2.5559, 49.0083 ]
+    }
+  }
+
 .. note::
 
    Currently, only casting between ``geometry`` and ``geography`` types is allowed.
@@ -659,47 +767,92 @@ OrderByExp
 
    order_by: (TableOrderBy_ | [ TableOrderBy_ ])
 
-E.g.
+*Example 1*
 
-.. parsed-literal::
+.. code-block:: graphql
 
-   order_by: {id: desc}
+  query {
+    author(order_by: {rating: desc}) {
+      name
+      rating
+    }
+  }
 
-or
+*Example 2*
 
-.. parsed-literal::
+.. code-block:: graphql
 
-   order_by: [{id: desc}, {author: {id: asc}}]
+  query {
+    article(order_by: [{id: desc}, {author: {id: asc}}]) {
+      title
+      rating
+    }
+  }
 
-or
+*Example 3*
 
-.. parsed-literal::
+.. code-block:: graphql
 
-   order_by: {articles_aggregate: {count: asc}}
+  query {
+    article(order_by: [{id: desc}, {author: {id: asc}}]) {
+      title
+      rating
+    }
+  }
 
 
 TableOrderBy
 """"""""""""
 
-For columns:
+**For columns**
 
 .. parsed-literal::
 
    {column: OrderByEnum_}
 
-For object relations:
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(order_by: {rating: asc}) {
+      title
+      content
+    }
+  }
+
+**For object relations**
 
 .. parsed-literal::
    {relation-name: TableOrderBy_}
 
-For array relations aggregate:
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(order_by: {author: {rating: desc}}) {
+      title
+      content
+    }
+  }
+
+**For array relations aggregate**
 
 .. parsed-literal::
    {relation-name_aggregate: AggregateOrderBy_}
 
-E.g.
+*Example*
 
-Order by type for "article" table:
+.. code-block:: graphql
+
+  query {
+    author(order_by: {articles_aggregate: {max: {rating: asc}}}) {
+      name
+    }
+  }
+
+Order by type for ``article`` table:
 
 .. code-block:: graphql
 
@@ -714,6 +867,8 @@ Order by type for "article" table:
      likes_aggregate: likes_aggregate_order_by
    }  
 
+.. _OrderByEnum:
+
 OrderByEnum
 ###########
 
@@ -738,16 +893,36 @@ OrderByEnum
 AggregateOrderBy
 ################
 
-Count aggregate
+**Count aggregate**
 
 .. parsed-literal::
    {count: OrderByEnum_}
 
-Operation aggregate
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    author(order_by: {articles_aggregate: {count: desc}}) {
+      name
+    }
+  }
+
+**Operation aggregate**
 
 .. parsed-literal::
    {op_name: TableAggOpOrderBy_}
 
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    author (order_by: {articles_aggregate: {sum: {id: desc}}}) {
+      id
+    }
+  }
+
 Available operations are ``sum``, ``avg``, ``max``, ``min``, ``stddev``, ``stddev_samp``,
 ``stddev_pop``, ``variance``, ``var_samp`` and ``var_pop``.
 
@@ -766,3 +941,14 @@ PaginationExp
 
    limit: Integer
    [offset: Integer]
+
+*Example*
+
+.. code-block:: graphql
+
+  query {
+    article(limit: 6, offset: 2) {
+      title
+      content
+    }
+  }

docs/graphql/manual/api-reference/schema-metadata-api/manage-metadata.rst

@@ -41,7 +41,7 @@ replace_metadata
 ``replace_metadata`` is used to replace/import metadata into Hasura. Existing
 metadata will be replaced with the new one.
 
-.. code-block:: none
+.. code-block:: http
 
     POST /v1/query HTTP/1.1
     Content-Type: application/json
@@ -49,7 +49,7 @@ metadata will be replaced with the new one.
 
     {
         "type" : "replace_metadata",
-       "args": <metadata-as-json-object>
+        "args": "<metadata-as-json-object>"
     }
 
 .. _replace_metadata_syntax:
@@ -137,7 +137,7 @@ get_inconsistent_metadata
        "args": {}
    }
 
-Response:-
+Response:
 
 .. code-block:: json
 

docs/graphql/manual/api-reference/schema-metadata-api/permission.rst

@@ -166,7 +166,23 @@ InsertPermission
 drop_insert_permission
 ----------------------
 
-Drop an existing insert permission for a role on a table.
+The ``drop_insert_permission`` API is used to drop an existing insert permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_insert_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user"
+       }
+   }
 
 .. _drop_insert_permission_syntax:
 
@@ -302,7 +318,23 @@ SelectPermission
 drop_select_permission
 ----------------------
 
-Drop an existing select permission for a role on a table.
+The ``drop_select_permission`` is used to drop an existing select permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_select_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user"
+       }
+   }
 
 .. _drop_select_permission_syntax:
 
@@ -445,7 +477,23 @@ UpdatePermission
 drop_update_permission
 ----------------------
 
-Drop an existing update permission for a role on a table.
+The ``drop_update_permission`` API is used to drop an existing update permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_update_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user"
+       }
+   }
 
 .. _drop_update_permission_syntax:
 
@@ -552,7 +600,23 @@ DeletePermission
 drop_delete_permission
 ----------------------
 
-Drop an existing delete permission for a role on a table.
+The ``drop_delete_permission`` API is used to drop an existing delete permission for a role on a table.
+
+An example:
+
+.. code-block:: http
+
+   POST /v1/query HTTP/1.1
+   Content-Type: application/json
+   X-Hasura-Role: admin
+
+   {
+       "type" : "drop_delete_permission",
+       "args" : {
+           "table" : "article",
+           "role" : "user"
+       }
+   }
 
 .. _drop_delete_permission_syntax:
 

docs/graphql/manual/queries/query-filters.rst

@@ -1725,7 +1725,7 @@ Columns of type ``geography`` are more accurate, but they don’t support as man
 The TRUE expression ( **{ }** )
 -------------------------------
 
-The expression ``{}`` evaluates to ``true`` for all objects.
+The expression ``{}`` evaluates to ``true`` if an object exists (even if it's ``null``).
 
 **For example**: