graphql-engine/docs/graphql/core/actions/action-relationships.rst
Solomon Bothwell 9c27f66768 docs: add actions transforms content
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/2540
Co-authored-by: Tirumarai Selvan <8663570+tirumaraiselvan@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
GitOrigin-RevId: d9318aca67646c29b5d951a5d0603fc463e1467b
2021-11-02 14:36:36 +00:00

174 lines
4.4 KiB
ReStructuredText

.. meta::
:description: Manage Hasura actions relationships
:keywords: hasura, docs, actions, relationships
.. _actions_relationships:
Actions relationships
=====================
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
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:
.. code-block:: graphql
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:
.. code-block:: graphql
:emphasize-lines: 3
type UpdateAuthorOutput {
author_id : Int!
updatedAuthor: author
}
Now we can make a mutation request with a complex response such as:
.. code-block:: graphql
mutation updateAuthorAndGetArticles($id: Int, $name: String) {
updateAuthor(id: $id, name: $name) {
author_id
updatedAuthor {
id
name
articles {
id
title
}
}
}
}
See more details at :ref:`custom object type relationships <custom_object_type_relationships>`
Creating relationships for custom object types
**********************************************
You can create relationships for custom output types by:
.. rst-class:: api_tabs
.. tabs::
.. tab:: 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:
.. thumbnail:: /img/graphql/core/actions/actions-relationship.png
:alt: Console action relationship
Hit ``Save`` to create the relationship.
.. tab:: CLI
Go to ``metadata/actions.yaml`` in the Hasura project directory.
Update the definition of the ``UpdateAuthorOutput`` object type as:
.. code-block:: yaml
:emphasize-lines: 4-11
- 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.
.. tab:: API
Action relationships can be added while defining custom types via the :ref:`set_custom_types metadata API <metadata_set_custom_types>`:
.. code-block:: http
:emphasize-lines: 20-29
POST /v1/query 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"
}
}
]
}
]
}
}
.. admonition:: Additional Resources
Introduction to Hasura Actions - `View Recording <https://hasura.io/events/webinar/hasura-actions/?pg=docs&plcmt=body&cta=view-recording&tech=>`__.