update actions docs (#4007)

docs/graphql/manual/actions/action-handlers.rst

@@ -46,13 +46,14 @@ response type. The HTTP status code must be ``2xx`` for a successful response.
 Returning an error response
 ---------------------------
 
-To return an error response, you must send back an error object or a list of
+To return an error response, you must send back an error object.
-error objects. An error object looks like:
+An error object looks like:
 
 .. code-block:: json
 
     {
-      "message": "<error message>"
+      "message": "<mandatory error message>",
+      "code": "<optional error code>"
     }
 
 The HTTP status code must be ``4xx`` for an error response.

docs/graphql/manual/actions/action-relationships.rst

@@ -0,0 +1,119 @@
+Connecting actions with the rest of the graph
+=============================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Use case
+--------
+
+Actions are a way to extend your GraphQL schema by adding custom mutations. It
+is a typical use case that the custom actions' response is actually related to
+existing objects in the schema. e.g. a custom ``insertAuthor`` action will be
+related to the ``author`` object in the schema. Hence, we would want to be able
+to get information about the ``author`` from the graph as a response of the
+``insertAuthor`` mutation.
+
+Using custom object types relationships
+---------------------------------------
+
+Actions can be connected to the rest of the graph by setting up
+:ref:`relationships <custom_object_type_relationships>` on its return output
+type.
+
+This allows complex responses to be returned as an action's response traversing
+the graph via the output type's relationships.
+
+**For example**, given the action:
+
+.. code-block:: graphql
+
+  type Mutation {
+    updateAuthor (
+      id: Int!
+      name: String!
+    ): UpdateAuthorOutput
+  }
+
+  type UpdateAuthorOutput {
+     author_id : Int!
+  }
+
+We can create an **object relationship** called ``updatedAuthor`` between the
+``UpdateAuthorOutput`` object type and the ``author`` table via the
+``UpdateAuthorOutput::author_id -> author::id`` fields.
+
+The object type will now be modified as:
+
+.. code-block:: graphql
+  :emphasize-lines: 3
+
+    type UpdateAuthorOutput {
+       author_id : Int!
+       updatedAuthor: author
+    }
+
+Now we can make a mutation request with a complex response such as:
+
+.. code-block:: graphql
+
+  mutation updateAuthorAndGetArticles($id: Int, $name: String) {
+    updateAuthor(id: $id, name: $name) {
+      author_id
+      updatedAuthor {
+        id
+        name
+        articles {
+          id
+          title
+        }
+      }
+    }
+  }
+
+Creating custom object type relationships
+*****************************************
+
+You can create relationships for custom output types by:
+
+.. rst-class:: api_tabs
+.. tabs::
+
+  .. tab:: Console
+
+     Head to the ``Actions -> [action-name] -> Relationships`` tab in the
+     console for the action returning the output type.
+
+     Set the output type relationship as shown below:
+
+     .. thumbnail:: ../../../img/graphql/manual/actions/actions-relationship.png
+        :alt: Console action relationship
+
+     Hit ``Save`` to create the relationship.
+
+  .. tab:: CLI
+
+     Go to ``metadata/actions.yaml`` in the Hasura project directory.
+
+     Update the definition of the ``UpdateAuthorOutput`` object type as:
+
+     .. code-block:: yaml
+       :emphasize-lines: 4-11
+
+       - custom_types
+         - objects
+           - name: UpdateAuthorOutput
+             relationships:
+             - name: updatedAuthor
+               type: object
+               remote_table:
+                 schema: public
+                 name: author
+               field_mapping:
+                 author_id: id
+
+
+     Save the changes and run ``hasura metadata apply`` to create the relationship.
+

docs/graphql/manual/actions/create.rst

@@ -27,6 +27,10 @@ Step 0: Setup
 .. rst-class:: api_tabs
 .. tabs::
 
+  .. tab:: Console
+
+     There is no setup required for defining actions via the console.
+
   .. tab:: CLI
 
      .. :ref:`Install <install_hasura_cli>` or :ref:`update to <hasura_update-cli>` the latest version of Hasura CLI.

docs/graphql/manual/actions/index.rst

@@ -124,3 +124,4 @@ Learn more
   async-actions
   Codegen <codegen>
   derive
+  action-relationships

docs/graphql/manual/actions/types/index.rst

@@ -44,6 +44,41 @@ This is an object type called ``UserInfo`` that has two fields:
   Hasura does not allow a field of an object type to be another object type,
   i.e. the fields of an object type can only be ``scalars`` and ``enums``.
 
+  For a more complicated structure, the object types can be connected to the rest
+  of the graph via :ref:`relationships <custom_object_type_relationships>`.
+
+.. _custom_object_type_relationships:
+
+Relationships
+*************
+
+Custom object types can be connected to the rest of the graph by setting up
+:ref:`relationships <relationships>` with tables/views.
+
+**For example**, given the object type:
+
+.. code-block:: graphql
+
+  type UserInfo {
+    accessToken: String!
+    userId: Int!
+  }
+
+We can create an **object relationship** called ``createdUser`` between the
+``UserInfo`` object type and the ``user`` table via the
+``UserInfo::userId -> user::id`` fields.
+
+The object type will now be modified as:
+
+.. code-block:: graphql
+  :emphasize-lines: 4
+
+  type UserInfo {
+    accessToken: String!
+    userId: Int!
+    createdUser: user
+  }
+
 Input types
 -----------
 

docs/graphql/manual/api-reference/schema-metadata-api/event-triggers.rst

@@ -77,7 +77,7 @@ Args syntax
      - Name of the event trigger
    * - table
      - true
-     - [ :ref:`QualifiedTable <QualifiedTable>` ]
+     - :ref:`QualifiedTable <QualifiedTable>`
      - Object with table name and schema
    * - webhook
      - true

docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst

@@ -21,6 +21,8 @@ TableName
 
    String | QualifiedTable_
 
+.. _QualifiedTable:
+
 QualifiedTable
 ^^^^^^^^^^^^^^
 

docs/graphql/manual/deployment/downgrading.rst

@@ -36,16 +36,15 @@ described :ref:`here <hasura_metadata_schema>`. The schema of the catalogue is
 versioned. Updates to the Hasura GraphQL engine may have Hasura catalogue
 version bumps.
 
-During upgrades the server automatically migrates the catalogue to the latest
-version on startup.
-
 Downgrades to the catalogue need to be carried out manually in case you are
 attempting to downgrade to a lower Hasura GraphQL engine version.
 
-You can downgrade the catalogue from a particular version to a previous version
+From ``v1.2.0``, you can downgrade the catalogue from a particular version to a
-by executing the ``graphql-engine`` executable on the command line, with the
+previous version by executing the ``graphql-engine`` executable on the command
-``downgrade`` command, specifying the desired catalogue version using one of
+line, with the ``downgrade`` command, specifying the desired catalogue version
-the ``--to-`` flags.
+using one of the ``--to-`` flags. For earlier versions, it is recommended to
+first upgrade to the latest version and then use the ``downgrade`` command to
+downgrade to the desired version.
 
 The ``downgrade`` command is not part of the Hasura CLI but rather a command on
 ``graphql-engine`` itself. The way to execute this command is to run:

docs/graphql/manual/schema/relationships/index.rst

@@ -2,6 +2,9 @@
    :description: Manage relationships between tables/views in Hasura
    :keywords: hasura, docs, schema, relationship
 
+
+.. _relationships:
+
 Relationships between tables/views
 ==================================