graphql-engine/docs/graphql/core/actions/action-relationships.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

174 lines
4.4 KiB
ReStructuredText
Raw Normal View History

.. meta::
:description: Manage Hasura actions relationships
:keywords: hasura, docs, actions, relationships
.. _actions_relationships:
Actions relationships
=====================
2020-03-03 15:02:40 +03:00
.. contents:: Table of contents
:backlinks: none
:depth: 2
:local:
Introduction
------------
2020-03-03 15:02:40 +03:00
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
2020-03-03 15:02:40 +03:00
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
----------------------------------------
2020-03-03 15:02:40 +03:00
Actions can be connected to the rest of the graph by setting up relationships on
its return output type.
2020-03-03 15:02:40 +03:00
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.
2020-03-03 15:02:40 +03:00
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
**********************************************
2020-03-03 15:02:40 +03:00
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
2020-03-03 15:02:40 +03:00
: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=>`__.