mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 12:31:52 +03:00
5116e16e18
* add support for action queries * a new parameter `type` is added in the ArgumentDefinition, its value can be either `query` or `mutation` and it defaults to the latter * throw 400 when a query action is tried to explain * update the actions docs to include query actions * refactor the ToJSON and ToOrdJSON of ActionDefinition Co-authored-by: Rishichandra Wawhal <rishi@hasura.io> Co-authored-by: Tirumarai Selvan <tiru@hasura.io>
152 lines
4.5 KiB
ReStructuredText
152 lines
4.5 KiB
ReStructuredText
.. meta::
|
|
:description: Hasura actions
|
|
:keywords: hasura, docs, actions
|
|
|
|
.. _actions:
|
|
|
|
Actions (beta)
|
|
==============
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 2
|
|
:local:
|
|
|
|
What are actions?
|
|
-----------------
|
|
|
|
Actions are a way to extend Hasura's schema with custom business
|
|
logic using custom queries and mutations. Actions can be
|
|
added to Hasura to handle various use cases such as data validation, data
|
|
enrichment from external sources and any other complex business logic.
|
|
|
|
.. thumbnail:: ../../../img/graphql/manual/actions/actions-hl-arch.png
|
|
:class: no-shadow
|
|
:alt: Actions high level architecture
|
|
|
|
.. admonition:: Supported from
|
|
|
|
Actions are currently available in beta in the pre-release versions of ``v1.2.0``.
|
|
|
|
.. Actions are supported in versions ``v.1.2.0`` and above.
|
|
|
|
.. admonition:: Postgres support
|
|
|
|
Actions are supported for ``Postgres versions 10 or higher``.
|
|
|
|
Action description
|
|
------------------
|
|
|
|
An action consists of the following parts:
|
|
|
|
1. ``Type``: The type of the action (``query`` or ``mutation``)
|
|
2. ``Definition``: The definition of the query or mutation
|
|
3. ``Handler``: The logic to be run when the query or mutation is executed
|
|
4. ``Kind``: Sync or async
|
|
|
|
.. note::
|
|
|
|
In case of a query action, there is no ``Kind`` associated with the action.
|
|
A query action works like a ``Synchronous`` mutation action.
|
|
|
|
Type
|
|
****
|
|
|
|
Actions can be of two types:
|
|
|
|
- **Query action**: An action of type ``query`` extends the query root of the Hasura schema. This means that you can execute this action through a GraphQL query. Query actions must be used where you want to fetch data from a data source without changing anything on the data source.
|
|
- **Mutation action**: An action of type ``mutation`` extends the mutation root of the Hasura schema. This means that you can execute this action through a GraphQL mutation. Mutation actions must be used when you want to mutate the state of a data source and fetch some data.
|
|
|
|
Definition
|
|
**********
|
|
|
|
The action definition consists of the following:
|
|
|
|
- ``Action Name``: The action will be available as a query or mutation in the GraphQL
|
|
schema named as the action name
|
|
- ``Arguments``: Arguments are used to pass dynamic values along with the
|
|
query/mutation.
|
|
- ``Response type``: The GraphQL type of the response that the query or mutation will
|
|
return. Actions can only return object types.
|
|
|
|
For instance, consider this action definition:
|
|
|
|
.. code-block:: graphql
|
|
|
|
extend type Mutation {
|
|
userLogin(username: String!, password: String!): UserInfo
|
|
}
|
|
|
|
In this definition, we are extending the mutation root with an action called
|
|
``userLogin``.
|
|
|
|
- ``userLogin`` is the action name
|
|
- ``username`` and ``password`` are the arguments that accept non-nullable
|
|
string values.
|
|
- ``UserInfo`` is the response type of the action
|
|
|
|
**Custom Types**
|
|
|
|
An action must return an object type. This means, you will have to define your
|
|
custom types like so:
|
|
|
|
.. code-block:: graphql
|
|
|
|
type UserInfo {
|
|
accessToken: String!
|
|
userId: Int!
|
|
}
|
|
|
|
Read more about :ref:`custom types<custom_types>`.
|
|
|
|
Handler
|
|
*******
|
|
|
|
Once you define the action types, you also have to specify the logic to run
|
|
when the action is executed. This can be done in an HTTP webhook,
|
|
also called the action handler. It could be a REST endpoint or a serverless
|
|
function.
|
|
|
|
Learn more about :ref:`writing an action handler<action_handlers>`.
|
|
|
|
Kind
|
|
****
|
|
|
|
Mutation actions are of two kinds:
|
|
|
|
* **Synchronous actions**: Sync actions return a response to the client after
|
|
receiving a response from the handler.
|
|
* **Asynchronous actions**: :ref:`Async actions <async_actions>` return an
|
|
``action id`` as response to the client before receiving a response from the
|
|
handler and allow the client to subscribe to the actual response using the
|
|
``action id``.
|
|
|
|
Query actions don't have a kind, they always behave like ``Synchronous mutation actions``.
|
|
|
|
How it works?
|
|
-------------
|
|
|
|
* Hasura receives the action GraphQL query or mutation and converts this request into an
|
|
event payload.
|
|
* The event is captured, persisted and then delivered to the action handler with
|
|
the appropriate retry/delivery guarantees.
|
|
* The action handler runs and returns a response that is captured as an event
|
|
and again persisted to the event store.
|
|
* The action response is returned to the client synchronously or asynchronously
|
|
based on the kind.
|
|
|
|
Learn more
|
|
----------
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:titlesonly:
|
|
|
|
create
|
|
Custom types <types/index>
|
|
action-handlers
|
|
async-actions
|
|
Codegen <codegen>
|
|
derive
|
|
action-connect
|