update multiple mutation docs with nested insert (#1043)

docs/graphql/manual/mutations/insert.rst

@@ -132,60 +132,6 @@ Insert multiple objects of the same type in the same mutation
       }
     }
 
-Insert nested object and get nested object in response
-------------------------------------------------------
-**Example:** Insert a new ``article`` object with its ``author`` and return the inserted article object with its author in the response
-
-
-.. graphiql::
-  :view_only:
-  :query:
-    mutation insert_article {
-      insert_article(
-        objects: [
-          {
-            id: 21,
-            title: "Article 1",
-            content: "Sample article content",
-            author: {
-              data: {
-                id: 3,
-                name: "Sidney"
-              }
-            }
-          }
-        ]
-      ) {
-        returning {
-          id
-          title
-          author {
-            id
-            name
-          }
-        }
-      }
-    }
-  :response:
-    {
-      "data": {
-        "insert_article": {
-          "affected_rows": 2,
-          "returning": [
-            {
-              "id": 21,
-              "title": "Article 1",
-              "author": {
-                "id": 3,
-                "name": "Sidney"
-              }
-            }
-          ]
-        }
-      }
-    }
-
-
 Insert object and get nested object in response
 -----------------------------------------------
 **Example:** Insert a new ``article`` object and return the inserted article object with its author in the response
@@ -234,6 +180,60 @@ Insert object and get nested object in response
     }
 
 
+Insert object with nested object and get nested object in response
+------------------------------------------------------------------
+**Example:** Insert a new ``article`` object with its ``author`` and return the inserted article object with its author
+in the response
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation insert_article {
+      insert_article(
+        objects: [
+          {
+            id: 21,
+            title: "Article 1",
+            content: "Sample article content",
+            author: {
+              data: {
+                id: 11,
+                name: "Cory"
+              }
+            }
+          }
+        ]
+      ) {
+        affected_rows
+        returning {
+          id
+          title
+          author {
+            id
+            name
+          }
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "insert_article": {
+          "affected_rows": 2,
+          "returning": [
+            {
+              "id": 21,
+              "title": "Article 1",
+              "author": {
+                "id": 11,
+                "name": "Cory"
+              }
+            }
+          ]
+        }
+      }
+    }
+
 Set field to its default value during insert
 --------------------------------------------
 

docs/graphql/manual/mutations/multiple-mutations.rst

@@ -3,62 +3,103 @@ Multiple mutations in a request
 If multiple mutations are part of the same request, they are executed **sequentially**. If any of the mutations fail,
 all the executed mutations will be rolled back (i.e. all the mutations are run as a **transaction**).
 
-Example: Insert objects of different types in the same mutation
----------------------------------------------------------------
-Insert an ``author`` object and an ``article`` object written by the author:
+Run multiple top level mutations transactionally
+------------------------------------------------
+**Example:** Delete all ``article`` objects written by an author and update the ``author`` object
 
 .. graphiql::
   :view_only:
   :query:
-    mutation insert_author_and_article {
-      insert_author(
-        objects: [
-          {id: 11, name: "Jane"}
-        ]
+    mutation reset_author {
+      delete_article (
+        where: {author_id: {_eq: 6}}
+      ) {
+        affected_rows
+      }
+      update_author (
+        where: {id: {_eq: 6}}
+        _set: {name: "Cory"}
       ) {
-        affected_rows,
         returning {
           id
           name
+          articles {
+            id
+            title
+          }
         }
       }
+    }
+  :response:
+    {
+        "data": {
+          "delete_article": {
+            "affected_rows": 2
+          },
+          "update_author": {
+            "returning": [
+              {
+                "id": 6,
+                "name": "Cory",
+                "articles": []
+              }
+            ]
+          }
+        }
+      }
+
+Insert an object and a nested object in the same mutation
+---------------------------------------------------------
+If you are trying to insert multiple objects which have relationships between them, you can use nested inserts.
+
+**Example:** Insert a new ``article`` object with its ``author`` and return the inserted article object with its author
+in the response
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation insert_article {
       insert_article(
         objects: [
-          {id: 21, title: "Article 1", content: "Sample content", author_id: 11}
+          {
+            id: 21,
+            title: "Article 1",
+            content: "Sample article content",
+            author: {
+              data: {
+                id: 11,
+                name: "Cory"
+              }
+            }
+          }
         ]
       ) {
-        affected_rows,
+        affected_rows
         returning {
           id
           title
+          author {
+            id
+            name
+          }
         }
       }
     }
   :response:
     {
       "data": {
-        "insert_author": {
-          "affected_rows": 1,
-          "returning": [
-            {
-              "id": 11,
-              "name": "Jane"
-            }
-          ]
-        },
         "insert_article": {
-          "affected_rows": 1,
+          "affected_rows": 2,
           "returning": [
             {
-              "id": 21,
-              "title": "Article 1"
+                "id": 21,
+                "title": "Article 1",
+                "author": {
+                  "id": 11,
+                  "name": "Cory"
+                }
             }
           ]
         }
       }
     }
-
-..
-  Insert an object and a nested object in the same mutation
-  ---------------------------------------------------------
-  *This is currently work in progress*.

docs/graphql/manual/schema/views.rst

@@ -15,6 +15,6 @@ Please see the following pages for details about the above use-cases:
 
 - :doc:`../queries/control-access`
 
-- :doc:`../queries/aggregations`
+- :doc:`../queries/derived-data`