Actions relationships

Introduction

Actions are a way to extend your GraphQL schema with custom queries or mutations. It is quite a typical case that an action's response is actually related to existing objects in the schema and the action needs to be connected with the rest of the graph.

For example, 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 action output type's relationships

Actions can be connected to the rest of the graph by setting up 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:

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 using the UpdateAuthorOutput.author_id and author.id fields.

The object type will now be modified as:

type UpdateAuthorOutput {
  author_id: Int!
  updatedAuthor: author
}

Now we can make a mutation request with a complex response such as:

mutation updateAuthorAndGetArticles($id: Int, $name: String) {
  updateAuthor(id: $id, name: $name) {
    author_id
    updatedAuthor {
      id
      name
      articles {
        id
        title
      }
    }
  }
}

See more details at custom object type relationships

Creating relationships for custom object types

You can create relationships for custom output types by:

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:

Hit Save to create the relationship.

CLI

Go to metadata/actions.yaml in the Hasura project directory.

Update the definition of the UpdateAuthorOutput object type as:

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

API

Action relationships can be added while defining custom types via the set_custom_types metadata API:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "set_custom_types",
  "args": {
    "scalars": [],
    "enums": [],
    "input_objects": [],
    "objects": [
      {
        "name": "UpdateAuthorOutput",
        "fields": [
          {
            "name": "author_id",
            "type": "Int!"
          }
        ],
        "relationships": [
          {
            "name": "updatedAuthor",
            "type": "object",
            "remote_table": "author",
            "field_mapping": {
              "author_id": "id"
            }
          }
        ]
      }
    ]
  }
}

Additional Resources

Introduction to Hasura Actions - View Recording.