graphql-engine/docs/graphql/core/actions/derive.rst

.. meta::
   :description: Deriving Hasura actions
   :keywords: hasura, docs, actions, derive

.. _derive_actions:

Deriving actions
================

.. contents:: Table of contents
  :backlinks: none
  :depth: 1
  :local:

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:

.. code-block:: graphql

  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.

.. code-block:: graphql

  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:

.. rst-class:: api_tabs
.. tabs::

  .. tab:: Console

     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:

     .. thumbnail:: /img/graphql/core/actions/actions-derive-button.png
        :alt: Console derive action button

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

     .. thumbnail:: /img/graphql/core/actions/actions-derive-types.png
        :alt: Console derived action types


  .. tab:: CLI

     To create the derived action, run:

     .. code-block:: bash

         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.

     .. code-block:: graphql

        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.

.. rst-class:: api_tabs
.. tabs::

  .. tab:: 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.

    .. thumbnail:: /img/graphql/core/actions/actions-derive-codegen.png
       :alt: 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.

  .. tab:: CLI

    You will have to set up codegen in the CLI first to do this as explained in
    :ref:`actions-codegen-execute`

    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:

    .. code-block:: bash

        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 :ref:`backend-only-permissions`
for more details

.. note::

  Setting ``backend-only`` is currently available for insert mutations only.
  
.. admonition:: Additional Resources

  Introduction to Hasura Actions - `View Recording <https://hasura.io/events/webinar/hasura-actions/?pg=docs&plcmt=body&cta=view-recording&tech=>`__.