update query/mutation docs pages (#1426)

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

@@ -317,7 +317,7 @@ ColumnExp
 
 Operator
 ########
-Generic operators (all column types except json, jsonb) :
+**Generic operators (all column types except json, jsonb):**
 
 - ``_eq``
 - ``_neq``
@@ -328,7 +328,7 @@ Generic operators (all column types except json, jsonb) :
 - ``_gte``
 - ``_lte``
 
-JSONB operators:
+**JSONB operators:**
 
 .. list-table::
    :header-rows: 1
@@ -348,7 +348,7 @@ JSONB operators:
 
 (For more details on what these operators do, refer to `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
 
-Text related operators :
+**Text related operators :**
 
 - ``_like``
 - ``_nlike``
@@ -357,11 +357,11 @@ Text related operators :
 - ``_similar``
 - ``_nsimilar``
 
-Checking for ``null`` values :
+**Checking for NULL values:**
 
 - ``_is_null`` (takes true/false as values)
 
-PostGIS related operators on GEOMETRY columns :
+**PostGIS related operators on GEOMETRY columns:**
 
 .. list-table::
    :header-rows: 1
@@ -387,8 +387,9 @@ PostGIS related operators on GEOMETRY columns :
 
 (For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.)
 
-.. Note::
+.. note::
-   1. All operators take a json representation of ``geometry/geography`` values. Also see :doc:`here <../queries/query-filters>` for more query examples on these operators
+
+   1. All operators take a ``json`` representation of ``geometry/geography`` values.
    2. Input value for ``_st_d_within`` operator is an object:-
 
    .. parsed-literal::

docs/graphql/manual/mutations/delete.rst

@@ -6,6 +6,9 @@ Delete mutation
   :depth: 1
   :local:
 
+Auto-generated delete mutation schema
+-------------------------------------
+
 Here’s the schema for the delete mutation field for a table ``article``:
 
 .. code-block:: graphql
@@ -28,6 +31,11 @@ As you can see from the schema:
   for filtering options. Objects can be deleted based on filters on their own fields or those in their nested objects.
 - You can return the number of affected rows and the affected objects (with nested objects) in the response.
 
+.. note::
+
+  If a table is not in the ``public`` Postgres schema, the delete mutation field will be of the format
+  ``delete_<schema_name>_<table_name>``.
+
 Delete based on an object's fields
 ----------------------------------
 **Example:** Delete all articles rated less than 3:

docs/graphql/manual/mutations/index.rst

@@ -6,13 +6,18 @@ Mutations
   :depth: 1
   :local:
 
-GraphQL mutations are used to modify server-side data (i.e. write, update or delete data). As with queries, mutation
+GraphQL mutations are used to modify data on the server (i.e. write, update or delete data).
-fields are auto-generated based on the Postgres schema.
+
+Hasura GraphQL engine auto-generates mutations as part of the GraphQL schema from your Postgres schema model.
+
+Data of all tables in the database tracked by the GraphQL engine can be modified over the GraphQL endpoint.
+If you have a tracked table in your database, its insert/update/delete mutation fields are added as nested
+fields under the  ``mutation_root`` root level type.
 
 Types of mutation requests
 --------------------------
 
-Let's use this reference author/article schema to look at different types of mutations.
+The following types of mutation requests are possible:
 
 .. toctree::
   :maxdepth: 1

docs/graphql/manual/mutations/insert.rst

@@ -6,6 +6,9 @@ Insert mutation
   :depth: 1
   :local:
 
+Auto-generated insert mutation schema
+-------------------------------------
+
 Here’s the schema for the insert mutation field for a table ``article``:
 
 .. code-block:: graphql
@@ -29,6 +32,11 @@ As you can see from the schema:
 - You can pass an ``on_conflict`` argument to convert the mutation to an :doc:`upsert mutation <upsert>`
 - You can return the number of affected rows and the affected objects (with nested objects) in the response.
 
+.. note::
+
+  If a table is not in the ``public`` Postgres schema, the insert mutation field will be of the format
+  ``insert_<schema_name>_<table_name>``.
+
 Insert a single object
 ----------------------
 **Example:** Insert a new ``article`` object and return the inserted article object in the response

docs/graphql/manual/mutations/update.rst

@@ -6,6 +6,9 @@ Update mutation
   :depth: 1
   :local:
 
+Auto-generated update mutation schema
+-------------------------------------
+
 Here’s the schema for the update mutation field for a table ``article``:
 
 .. code-block:: graphql
@@ -32,9 +35,12 @@ As you can see from the schema:
 
 .. note::
 
-  At least any one of ``_set``, ``_inc`` operators or the jsonb operators ``_append``, ``_prepend``, ``_delete_key``,
+  - At least any one of ``_set``, ``_inc`` operators or the jsonb operators ``_append``, ``_prepend``, ``_delete_key``,
     ``_delete_elem``, ``_delete_at_path`` is required.
 
+  - If a table is not in the ``public`` Postgres schema, the update mutation field will be of the format
+    ``update_<schema_name>_<table_name>``.
+
 Update based on an object's fields
 ----------------------------------
 **Example:** Update the ``title``, ``content`` and ``rating`` of the article with a given ``id``:

docs/graphql/manual/queries/index.rst

@@ -6,13 +6,15 @@ Queries
   :depth: 1
   :local:
 
-Hasura GraphQL engine auto-generates queries and mutations as part of the GraphQL schema from your Postgres schema
+GraphQL queries are used to fetch data from the server.
-model. It generates a range of possible queries and operators that also work with relationships defined in your SQL
+
+Hasura GraphQL engine auto-generates queries as part of the GraphQL schema from your Postgres schema model.
+It generates a range of possible queries and operators that also work with relationships defined in your SQL
 schema.
 
-All tracked tables of the database can be queried and modified over the GraphQL endpoint. If you have a tracked table
+All tables of the database tracked by the GraphQL engine can be queried over the GraphQL endpoint.
-in your database, a query and insert/update/delete mutations each are added as nested fields under the root level
+If you have a tracked table in your database, its query field is added as a nested
-types, ``query_root`` and ``mutation_root`` respectively.
+field under the ``query_root`` root level type.
 
 Auto-generated query schema
 ---------------------------

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

@@ -43,16 +43,18 @@ For example, to fetch a list of authors who have articles with a rating greater
       }
     }
 
-Here ``_eq`` and ``_gt`` are examples of :ref:`comparison operators <Operator>` that can be used in the ``where`` argument to filter on
+Here ``_eq`` and ``_gt`` are examples of :ref:`comparison operators <Operator>` that can be used in the ``where``
-equality.
+argument to filter on equality.
 
 Let’s take a look at different operators that can be used to filter results and other advanced use cases:
 
 Equality operators (_eq and _neq)
 ---------------------------------
 The ``_eq`` (equal to) or the ``_neq`` (not equal to) operators are compatible with any Postgres type other than
-json or jsonB (like Integer, Float, Double, Text, Boolean, Date/Time/Timestamp, etc.). The following are examples of
+``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``,
-using the equality operators on different types.
+``Date``/``Time``/``Timestamp``, etc.).
+
+The following are examples of using the equality operators on different types.
 
 Example: Integer (works with Double, Float, Numeric, etc.)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -185,9 +187,10 @@ Fetch a list of articles that were published on a certain date (``published_on``
 Greater than or less than operators (_gt, _lt, _gte, _lte)
 ----------------------------------------------------------
 The ``_gt`` (greater than), ``_lt`` (less than), ``_gte`` (greater than or equal to),
-``_lte`` (less than or equal to) operators are compatible with any Postgres type other than json or jsonB
+``_lte`` (less than or equal to) operators are compatible with any Postgres type other than ``json`` or ``jsonB``
-(like Integer, Float, Double, Text, Boolean, Date/Time/Timestamp, etc.). The following are examples of using these
+(like ``Integer``, ``Float``, ``Double``, ``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.).
-operators on different types:
+
+The following are examples of using these operators on different types:
 
 
 Example: Integer (works with Double, Float, etc.)
@@ -308,8 +311,10 @@ Fetch a list of articles that were published on or after date "01/01/2018":
 List based search operators (_in, _nin)
 ---------------------------------------
 The ``_in`` (in a list) and ``_nin`` (not in list) operators are used to comparing field values to a list of values.
-They are compatible with any Postgres type other than json or jsonB (like Integer, Float, Double, Text, Boolean,
+They are compatible with any Postgres type other than ``json`` or ``jsonB`` (like ``Integer``, ``Float``, ``Double``,
-Date/Time/Timestamp, etc.). The following are examples of using these operators on different types:
+``Text``, ``Boolean``, ``Date``/``Time``/``Timestamp``, etc.).
+
+The following are examples of using these operators on different types:
 
 Example: Integer (works with Double, Float, etc.)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -475,22 +480,26 @@ Fetch a list of authors whose names begin with A or C (``similar`` is case-sensi
 
 PostGIS topology operators
 --------------------------
+
 The ``_st_contains``, ``_st_crosses``, ``_st_equals``, ``_st_intersects``, ``_st_overlaps``,
 ``_st_touches``, ``_st_within`` and ``_st_d_within`` operators are used to filter ``geometry`` like columns.
 For more details on what these operators do, refer to `PostGIS docs <http://postgis.net/workshops/postgis-intro/spatial_relationships.html>`__.
 
-Use ``json`` (`GeoJSON <https://tools.ietf.org/html/rfc7946>`_) representation of ``geometry`` values in ``variables`` as shown in the following examples
+Use ``json`` (`GeoJSON <https://tools.ietf.org/html/rfc7946>`_) representation of ``geometry`` values in
+``variables`` as shown in the following examples:
 
 
 Example: _st_within
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^
-Fetch a list of geometry values which are within the given ``polygon`` value
+Fetch a list of geometry values which are within the given ``polygon`` value:
 
 .. graphiql::
   :view_only:
   :query:
     query geom_table($polygon: geometry){
-      geom_table(where: {geom_col: {_st_within: $polygon}}){
+      geom_table(
+        where: {geom_col: {_st_within: $polygon}}
+      ){
         id
         geom_col
       }
@@ -512,36 +521,17 @@ Fetch a list of geometry values which are within the given ``polygon`` value
         ]
       }
     }
-
+  :variables:
-Variables for above query:-
-
-.. code-block:: json
-
     {
       "polygon": {
         "type": "Polygon",
         "coordinates": [
           [
-           [
+            [ 0, 0 ],
-             0,
+            [ 0, 2 ],
-             0
+            [ 2, 2 ],
-           ],
+            [ 2, 0 ],
-           [
+            [ 0, 0 ]
-             0,
-             2
-           ],
-           [
-             2,
-             2
-           ],
-           [
-             2,
-             0
-           ],
-           [
-             0,
-             0
-           ]
           ]
         ]
       }
@@ -549,13 +539,15 @@ Variables for above query:-
 
 Example: _st_d_within
 ^^^^^^^^^^^^^^^^^^^^^
-Fetch a list of geometry values which are 3 units from given ``point`` value
+Fetch a list of geometry values which are 3 units from given ``point`` value:
 
 .. graphiql::
   :view_only:
   :query:
     query geom_table($point: geometry){
-      geom_table(where: {geom_col: {_st_d_within: {distance: 3, from: $point}}}){
+      geom_table(
+        where: {geom_col: {_st_d_within: {distance: 3, from: $point}}}
+      ){
         id
         geom_col
       }
@@ -587,22 +579,14 @@ Fetch a list of geometry values which are 3 units from given ``point`` value
         ]
       }
     }
-
+  :variables:
-Variables for above query:-
-
-.. code-block:: json
-
     {
       "point": {
         "type": "Point",
-        "coordinates": [
+        "coordinates": [ 0, 0 ]
-          0,
-          0
-        ]
       }
     }
 
-
 Filter or check for null values
 -------------------------------
 Checking for null values can be achieved using the ``_is_null`` operator.
@@ -1061,7 +1045,7 @@ Fetch if **all** of the nested objects defined via an array relationship satisfy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As by default a row is returned if any of the nested objects satisfy a condition, to achieve the above we need to frame
-the ``where`` expression as ``{_not: {inverse-of-condition}}``. This reads as: fetch if not(any of the nested objects
+the ``where`` expression as ``{_not: {inverse-of-condition}}``. This reads as: fetch if not (any of the nested objects
 satisfy the inverted condition) i.e. all of the nested objects satisfy the condition.
 
 For example,
@@ -1162,7 +1146,7 @@ Fetch if **none** of the nested objects defined via an array relationship satisf
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As by default a row is returned if any of the nested objects satisfy a condition, to achieve the above we need to frame
-the ``where`` expression as ``{_not: {condition}}``. This reads as: fetch if not(any of the nested objects
+the ``where`` expression as ``{_not: {condition}}``. This reads as: fetch if not (any of the nested objects
 satisfy the condition) i.e. none of the nested objects satisy the condition.
 
 For example,