Deriving actions

Introduction

It is a typical requirement to run some custom business logic before actually executing a mutation, for example, to perform validations or to enrich some data from an external source. Actions can be used to achieve this.

To help with creation of such actions, Hasura lets you derive an action from an existing mutation by:

  • Auto-generating the GraphQL types defining the action
  • Generating the handler code to delegate the action back to the original mutation after executing some business logic

Generate derived action GraphQL types

Hasura can generate the relevant GraphQL types required to define an action given a mutation request.

For example, let’s say we would like to derive an action from the mutation:

mutation insertAuthor {
  insert_author_one(
    object: {
      name: "Some name"
    }) {
    id
    name
  }
}

As the derived action will need to accept some arguments, we can convert the above mutation to use variables instead which can then become arguments to our derived action.

mutation insertAuthor($name: String) {
  insert_author_one(
    object: {
      name: $name
    }) {
    id
    name
  }
}

Now that we have a mutation with arguments being accepted as variables, we can derive our action:

Head to the GraphiQL tab of the console and paste / generate your query in the GraphiQL window.

Next hit the Derive action button as shown below:

Console derive action button

This will redirect you to the Add a new action page with the action definition auto filled.

Console derived action types

To create the derived action, run:

hasura actions create insertAuthor --derive-from 'mutation insertAuthor($name: String) {
     insert_author_one(
       object: {
         name: $name
     }) {
     id
     name
   }
 }'

This will open up an editor with metadata/actions.graphql with the following action types auto filled.

type Mutation {
  insertAuthor (
    name: String
  ): InsertAuthorOutput
}

type InsertAuthorOutput {
   id : Int!
   name : String!
}

Note

The action name will be picked up from the argument of the command and not the mutation string.

Note

  • The derived output type will be derived from the actual output type of the original mutation and not the mutation string.
  • As currently custom object types can only have scalar / enum fields any object type fields in the original output type will be dropped in the derived output type.

Generate handler code for a derived action

For a derived action, Hasura can generate the relevant handler code to delegate the action back to the original mutation.

Head to the Actions -> [action-name] -> Codegen tab in the console

You can select the framework of your choice to get the corresponding handler boilerplate code.

Console derived action codegen

Note

The information about derived actions are stored locally on the browser and hence it is currently only possible to generate the delegation code from the browser where the action was created.

You will have to set up codegen in the CLI first to do this as explained in Generating handler code for your action

After saving the GraphQL types generated by the actions create command in the previous section, the CLI will prompt you if you would like to generate the corresponding codegen files. Hit y to generate the codegen files with the delegation logic.

Note

The CLI does not persist information about derived actions. Hence it is currently only possible to generate handler files with the delegation logic during action creation.