Deriving Actions

Introduction

It is a typical requirement to run some custom business logic before actually executing a mutation / query, 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 query or mutation by:

• Auto-generating the GraphQL types defining the action
• Generating the handler code to delegate the action back to the original query or 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 GraphQL operation.

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:

Console

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

Next hit the Derive action button as shown below:

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

CLI

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 query or mutation and not the selection-set of the given query or 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 operation.

Console

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.

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.

CLI

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.

The CLI does not persist information about derived actions. Hence if you wish to generate the delegation code, you might want to pass the query or mutation string while running the codegen command:

hasura actions codegen <action-name> --derive-from '<query/mutation string>'

Hiding the original mutation in the API

Once a mutation is derived, you might want to hide it from your public GraphQL API but still want to use it from your action handler.

To achieve this you can mark the mutation as backend_only so that it can be accessed only via "trusted sources". See Backend only for more details

Setting backend-only is currently available for insert, update and delete mutations.

Additional Resources

Introduction to Hasura Actions - View Recording.