AshGraphql.Resource (ash_graphql v0.16.28) View Source
This Ash resource extension adds configuration for exposing a resource in a graphql.
Table of Contents
- graphql
- queries
- get
- read_one
- list
- mutations
- create
- update
- destroy
- managed_relationships
- managed_relationship
- queries
graphql
Configuration for a given resource in graphql
- queries
- get
- read_one
- list
- mutations
- create
- update
- destroy
- managed_relationships
- managed_relationship
Examples:
graphql do
type :post
queries do
get :get_post, :read
list :list_posts, :read
end
mutations do
create :create_post, :create
update :update_post, :update
destroy :destroy_post, :destroy
end
end
:type
- Required. The type to use for this entity in the graphql schema:primary_key_delimiter
- If a composite primary key exists, this must be set to determine theid
field value:depth_limit
- A simple way to prevent massive queries.:relay?
- NOT YET SUPPORTED
If true, the graphql queries/resolvers for this resource will be built to honor the relay specification.
The two changes that are made currently are:the type for the resource will implement the
Node
interfacepagination over that resource will behave as a Connection. The default value is
false
.
queries
Queries (read actions) to expose for the resource.
Examples:
queries do
get :get_post, :read
read_one :current_user, :current_user
list :list_posts, :read
end
get
A query to fetch a record by primary key
Introspection Target:
Examples:
get :get_post, :read
:name
- The name to use for the query. The default value is:get
.:action
- Required. The action to use for the query.:identity
- false The identity to use for looking up the record. Passfalse
to not use an identity.:allow_nil?
- Whether or not the action can return nil. The default value istrue
.:modify_resolution
- An MFA that will be called with the resolution, the query, and the result of the action as the first three arguments (followed by the arguments in the mfa). Must return a new absinthe resolution. This can be used to implement things like setting cookies based on resource actions. A method of using resolution context for that is documented here: https://hexdocs.pm/absinthe_plug/Absinthe.Plug.html#module-before-send
Important if you are modifying the context, then you should also setas_mutation?
to true and represent this in your graphql as a mutation. Seeas_mutation?
for more.:as_mutation?
- Places the query in themutations
key instead. The use cases for this are likely very minimal.
If you have a query that needs to modify the graphql context usingmodify_resolution
, then you should likely set this as well. A simple example might be alog_in
, which could be a read action on the user that accepts an email/password, and should then set some context in the graphql inside ofmodify_resolution
. Once in the context, you can see the guide referenced inmodify_resolution
for more on setting the session or a cookie with an auth token. The default value isfalse
.
read_one
A query to fetch a record
Introspection Target:
Examples:
read_one :current_user, :current_user
:name
- The name to use for the query. The default value is:read_one
.:action
- Required. The action to use for the query.:allow_nil?
- Whether or not the action can return nil. The default value istrue
.
list
A query to fetch a list of records
Introspection Target:
Examples:
list :list_posts, :read
:name
- The name to use for the query. The default value is:list
.:action
- Required. The action to use for the query.
mutations
Mutations (create/update/destroy actions) to expose for the resource.
Examples:
mutations do
create :create_post, :create
update :update_post, :update
destroy :destroy_post, :destroy
end
create
A mutation to create a record
Introspection Target:
Examples:
create :create_post, :create
:name
- The name to use for the mutation. The default value is:get
.:action
- Required. The action to use for the mutation.:upsert?
- Whether or not to use theupsert?: true
option when callingYourApi.create/2
. The default value isfalse
.:modify_resolution
- An MFA that will be called with the resolution, the changeset, and the result of the action as the first three arguments (followed by the arguments in the mfa). Must return a new absinthe resolution. This can be used to implement things like setting cookies based on resource actions. A method of using resolution context for that is documented here: https://hexdocs.pm/absinthe_plug/Absinthe.Plug.html#module-before-send
update
A mutation to update a record
Introspection Target:
Examples:
update :update_post, :update
:name
- The name to use for the mutation. The default value is:get
.:action
- Required. The action to use for the mutation.:identity
- The identity to use to fetch the record to be updated.
If no identity is required (e.g for a read action that already knows how to fetch the item to be updated), usefalse
.:read_action
- The read action to use to fetch the record to be updated. Defaults to the primary read action.
destroy
A mutation to destroy a record
Introspection Target:
Examples:
destroy :destroy_post, :destroy
:name
- The name to use for the mutation. The default value is:get
.:action
- Required. The action to use for the mutation.:read_action
- The read action to use to fetch the record to be destroyed. Defaults to the primary read action.:identity
- The identity to use to fetch the record to be destroyed. If no identity is required (e.g for a read action that already knows how to fetch the item to be updated), usefalse
.
managed_relationships
Generates input objects for manage_relationship
arguments on reosurce actions.
Examples:
managed_relationships do
manage_relationship :create_post, :comments
end
managed_relationship
Instructs ash_graphql that a given argument with a manage_relationship
change should have its input objects derived automatically from the potential actions to be called.
For example, given an action like:
actions do
create :create do
argument :comments, {:array, :map}
change manage_relationship(:comments, type: :direct_control) # <- we look for this change with a matching argument name
end
end
You could add the following managed_relationship
graphql do
...
managed_relationships do
managed_relationship :create_post, :comments
end
end
By default, the {:array, :map}
would simply be a json[]
type. If the argument name
is placed in this list, all of the potential actions that could be called will be combined
into a single input object. If there are type conflicts (for example, if the input could create
or update a record, and the create and update actions have an argument of the same name but with a different type),
a warning is emitted at compile time and the first one is used. If that is insufficient, you will need to do one of the following:
1.) provide the :types
option to the managed_relationship
constructor (see that option for more)
2.) define a custom type, with a custom input object (see the custom types guide), and use that custom type instead of :map
3.) change your actions to not have overlapping inputs with different types
Introspection Target:
AshGraphql.Resource.ManagedRelationship
:argument
- Required. The argument for which an input object should be derived.:action
- The action that accepts the argument:lookup_with_primary_key?
- If the managed_relationship hason_lookup
behavior, this option determines whether or not the primary key is provided in the input object for looking up.
This option is ignored if there is noon_lookup
.:lookup_identities
- If the managed_relationship hason_lookup
behavior, this option determines which identities are provided in the input object for looking up.
This option is ignored if there is noon_lookup
. By default all identities are provided.:type_name
- The name of the input object that will be derived. Defaults to<action_type>_<resource>_<argument_name>_input
Because multiple actions could potentially be managing the same relationship, it isn't suficcient to default to something like<resource>_<relationship>_input
. Additionally, Ash doesn't expose resource action names by default, meaning that there is no automatic way to ensure that all of these have a default name that will always be unique. If you have multiple actions of the same type that manage a relationship with an argument of the same name, you will get a compile-time error.:types
- A keyword list of field names to their graphql type identifiers.
Since managed relationships can ultimately call multiple actions, there is the possibility of field type conflicts. Use this to determine the type of fields and remove the conflict warnings.
Fornon_null
use{:non_null, type}
, and for a list, use{:array, type}
, for example:{:non_null, {:array, {:non_null, :string}}}
for a non null list of non null strings.
To remove a key from the input object, simply passnil
as the type.