document unique/primary key constraint requirement for mutation response (#1776)

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

@@ -238,11 +238,34 @@ Mutation Response
 ^^^^^^^^^^^^^^^^^
 .. code-block:: none
 
+    # if table has atleast one primary key or
+    # one unique constraint with not null columns
     {
       affected_rows
       returning {
-        response-field1
-        response-field2
+        col-field1
+        col-field2
+        ..
+        relation1{
+          relation1-field1
+          relation1-field2
+          ..
+        }
+        relation2{
+          relation2-field1
+          relation2-field2
+          ..
+        }
+        ..
+      }
+    }
+
+    # if table has no primary key or unique constraints
+    {
+      affected_rows
+      returning {
+        col-field1
+        col-field2
         ..
       }
     }
@@ -251,6 +274,22 @@ E.g.:
 
 .. code-block:: graphql
 
+    # if table has atleast one primary key or
+    # one unique constraint with not null columns
+    {
+      affected_rows
+      returning {
+        id
+        author_id
+        articles{
+          id
+          title
+          content
+        }
+      }
+    }
+
+    # if table has no primary key or unique constraints
     {
       affected_rows
       returning {
@@ -266,6 +305,8 @@ E.g.:
 
 .. code-block:: none
 
+    # if table has atleast one primary key or
+    # one unique constraint with not null columns
     objects: [
       {
         field1: value,
@@ -282,12 +323,23 @@ E.g.:
       },
       ..
     ]
-    # no nested objects
+
+    # if table has no primary key or unique constraints
+    objects: [
+      {
+         col_field1: value,
+         col_field2: value
+         ..
+      },
+      ..
+    ]
 
 E.g.:
 
 .. code-block:: graphql
     
+    # if table has atleast one primary key or
+    # one unique constraint with not null columns
     objects: [
       {
         title: "Software is eating the world",
@@ -301,6 +353,14 @@ E.g.:
       }
     ]
 
+    # if table has no primary key or unique constraints
+    objects: [
+      {
+        title: "Software is eating the world",
+        content: "This week, Hewlett-Packard..."
+      }
+    ]
+
 .. _ConflictClause:
 
 **on_conflict** argument

docs/graphql/manual/mutations/delete.rst

@@ -35,8 +35,10 @@ See the :ref:`delete mutation API reference <delete_syntax>` for the full specif
 
 .. 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>``.
+  - If a table is not in the ``public`` Postgres schema, the delete mutation field will be of the format
+    ``delete_<schema_name>_<table_name>``.
+  - To fetch nested objects using relationships in the mutation response, the table needs to have either a primary
+    key or a unique constraint with not null columns.
 
 Delete based on an object's fields
 ----------------------------------

docs/graphql/manual/mutations/insert.rst

@@ -36,8 +36,10 @@ See the :ref:`insert mutation API reference <insert_upsert_syntax>` for the full
 
 .. 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>``.
+  - If a table is not in the ``public`` Postgres schema, the insert mutation field will be of the format
+    ``insert_<schema_name>_<table_name>``.
+  - To fetch nested objects using relationships in the mutation response, the table needs to have either a primary
+    key or a unique constraint with not null columns.
 
 Insert a single object
 ----------------------
@@ -215,6 +217,10 @@ Insert an object and get a nested object in response
       }
     }
 
+.. note::
+  
+  For this to work, the parent table (*in this case,* ``article``) needs to have either a primary key or a
+  unique constraint.
 
 Insert an object and its nested object in the same mutation
 -----------------------------------------------------------
@@ -270,6 +276,11 @@ in the response
       }
     }
 
+.. note::
+  
+  For this to work, the parent table (*in this case,* ``article``) needs to have either a primary key or a
+  unique constraint.
+
 Insert an object with a JSONB column
 ------------------------------------
 **Example:** Insert a new ``author`` object with a JSONB ``address`` column

docs/graphql/manual/mutations/update.rst

@@ -39,9 +39,10 @@ See the :ref:`update mutation API reference <update_syntax>` for the full specif
 
   - 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>``.
+  - To fetch nested objects using relationships in the mutation response, the table needs to have either a primary
+    key or a unique constraint with not null columns.
 
 Update based on an object's fields
 ----------------------------------

docs/graphql/manual/mutations/upsert.rst

@@ -145,6 +145,10 @@ You can specify ``on_conflict`` clause while inserting nested objects
       }
     }
 
+.. note::
+  
+  For this to work, the parent table (*in this case,* ``author``) needs to have either a primary key or a
+  unique constraint.
 
 .. admonition:: Edge-cases