Skip to main content
Version: v2.x

Deriving Actions


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" }) {

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 }) {

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

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:

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
  • 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.

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

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.

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.