DSL-AshGraphql.Resource.md

DSL: AshGraphql.Resource

This Ash resource extension adds configuration for exposing a resource in a graphql.

graphql

Configuration for a given resource in graphql

Nested DSLs

• queries
  • get
  • read_one
  • list
  • action
• mutations
  • create
  • update
  • destroy
  • action
• subscriptions
  • subscribe
• 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

Options

Name	Type	Default	Docs
type{: #graphql-type }	atom		The type to use for this entity in the graphql schema. If the resource doesn't have a type, it also needs to have generate_object? false and can only expose generic action queries.
derive_filter?{: #graphql-derive_filter? }	boolean	true	Set to false to disable the automatic generation of a filter input for read actions.
derive_sort?{: #graphql-derive_sort? }	boolean	true	Set to false to disable the automatic generation of a sort input for read actions.
encode_primary_key?{: #graphql-encode_primary_key? }	boolean	true	For resources with composite primary keys, or primary keys not called :id, this will cause the id to be encoded as a single id attribute, both in the representation of the resource and in get requests
relationships{: #graphql-relationships }	list(atom)		A list of relationships to include on the created type. Defaults to all public relationships where the destination defines a graphql type.
paginate_relationship_with{: #graphql-paginate_relationship_with }	keyword	[]	A keyword list indicating which kind of pagination should be used for each has_many and many_to_many relationships, e.g. related_things: :keyset, other_related_things: :offset. Valid pagination values are nil, :offset, :keyset and :relay.
field_names{: #graphql-field_names }	keyword		A keyword list of name overrides for attributes.
hide_fields{: #graphql-hide_fields }	list(atom)		A list of attributes to hide from the domain
show_fields{: #graphql-show_fields }	list(atom)		A list of attributes to show in the domain. If not specified includes all (excluding hide_fiels).
argument_names{: #graphql-argument_names }	keyword		A nested keyword list of action names, to argument name remappings. i.e create: [arg_name: :new_name]
keyset_field{: #graphql-keyset_field }	atom		If set, the keyset will be displayed on all read actions in this field. It will be nil unless at least one of the read actions on a resource uses keyset pagination or it is the result of a mutation
attribute_types{: #graphql-attribute_types }	keyword		A keyword list of type overrides for attributes. The type overrides should refer to types available in the graphql (absinthe) schema. list_of/1 and non_null/1 helpers can be used.
attribute_input_types{: #graphql-attribute_input_types }	keyword		A keyword list of input type overrides for attributes. The type overrides should refer to types available in the graphql (absinthe) schema. list_of/1 and non_null/1 helpers can be used.
argument_input_types{: #graphql-argument_input_types }	keyword		A keyword list of actions and their input type overrides for arguments. The type overrides should refer to types available in the graphql (absinthe) schema. list_of/1 and non_null/1 helpers can be used.
primary_key_delimiter{: #graphql-primary_key_delimiter }	String.t	"~"	If a composite primary key exists, this can be set to determine delimiter used in the id field value.
depth_limit{: #graphql-depth_limit }	integer		A simple way to prevent massive queries.
generate_object?{: #graphql-generate_object? }	boolean	true	Whether or not to create the GraphQL object, this allows you to manually create the GraphQL object.
filterable_fields{: #graphql-filterable_fields }	list(atom)		A list of fields that are allowed to be filtered on. Defaults to all filterable fields for which a GraphQL type can be created.
nullable_fields{: #graphql-nullable_fields }	atom | list(atom)		Mark fields as nullable even if they are required. This is useful when using field policies. See the authorization guide for more.

graphql.queries

Queries (read actions) to expose for the resource.

Nested DSLs

• get
• read_one
• list
• action

Examples

queries do
  get :get_post, :read
  read_one :current_user, :current_user
  list :list_posts, :read
end

graphql.queries.get

get name, action

A query to fetch a record by primary key

Examples

get :get_post, :read

Arguments

Name	Type	Default	Docs
name{: #graphql-queries-get-name }	atom	:get	The name to use for the query.
action{: #graphql-queries-get-action .spark-required}	atom		The action to use for the query.

Options

Name	Type	Default	Docs
identity{: #graphql-queries-get-identity }	atom		The identity to use for looking up the record. Pass false to not use an identity.
allow_nil?{: #graphql-queries-get-allow_nil? }	boolean	true	Whether or not the action can return nil.
modify_resolution{: #graphql-queries-get-modify_resolution }	mfa		An MFA that will be called with the resolution, the query, and the result of the action as the first three arguments. See the the guide for more.
type_name{: #graphql-queries-get-type_name }	atom		Override the type name returned by this query. Must be set if the read action has metadata that is not hidden via the show_metadata key.
description{: #graphql-queries-get-description }	String.t		The query description that gets shown in the Graphql schema. If not provided, the action description will be used.
metadata_names{: #graphql-queries-get-metadata_names }	keyword	[]	Name overrides for metadata fields on the read action.
metadata_types{: #graphql-queries-get-metadata_types }	keyword	[]	Type overrides for metadata fields on the read action.
show_metadata{: #graphql-queries-get-show_metadata }	list(atom)		The metadata attributes to show. Defaults to all.
as_mutation?{: #graphql-queries-get-as_mutation? }	boolean	false	Places the query in the mutations key instead. Not typically necessary, but is often paired with as_mutation?. See the the guide for more.
relay_id_translations{: #graphql-queries-get-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.
hide_inputs{: #graphql-queries-get-hide_inputs }	list(atom)	[]	A list of inputs to hide from the mutation.

Introspection

Target: AshGraphql.Resource.Query

graphql.queries.read_one

read_one name, action

A query to fetch a record

Examples

read_one :current_user, :current_user

Arguments

Name	Type	Default	Docs
name{: #graphql-queries-read_one-name }	atom	:get	The name to use for the query.
action{: #graphql-queries-read_one-action .spark-required}	atom		The action to use for the query.

Options

Name	Type	Default	Docs
allow_nil?{: #graphql-queries-read_one-allow_nil? }	boolean	true	Whether or not the action can return nil.
type_name{: #graphql-queries-read_one-type_name }	atom		Override the type name returned by this query. Must be set if the read action has metadata that is not hidden via the show_metadata key.
description{: #graphql-queries-read_one-description }	String.t		The query description that gets shown in the Graphql schema. If not provided, the action description will be used.
metadata_names{: #graphql-queries-read_one-metadata_names }	keyword	[]	Name overrides for metadata fields on the read action.
metadata_types{: #graphql-queries-read_one-metadata_types }	keyword	[]	Type overrides for metadata fields on the read action.
show_metadata{: #graphql-queries-read_one-show_metadata }	list(atom)		The metadata attributes to show. Defaults to all.
as_mutation?{: #graphql-queries-read_one-as_mutation? }	boolean	false	Places the query in the mutations key instead. Not typically necessary, but is often paired with as_mutation?. See the the guide for more.
relay_id_translations{: #graphql-queries-read_one-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.
hide_inputs{: #graphql-queries-read_one-hide_inputs }	list(atom)	[]	A list of inputs to hide from the mutation.

Introspection

Target: AshGraphql.Resource.Query

graphql.queries.list

list name, action

A query to fetch a list of records

Examples

list :list_posts, :read

list :list_posts_paginated, :read, relay?: true

Arguments

Name	Type	Default	Docs
name{: #graphql-queries-list-name }	atom	:get	The name to use for the query.
action{: #graphql-queries-list-action .spark-required}	atom		The action to use for the query.

Options

Name	Type	Default	Docs
relay?{: #graphql-queries-list-relay? }	boolean	false	If true, the graphql queries/resolvers for this resource will be built to honor the relay specification. See the relay guide for more.
paginate_with{: #graphql-queries-list-paginate_with }	:keyset | :offset | nil	:keyset	Determine the pagination strategy to use, if multiple are available. If nil, no pagination is applied, otherwise the given strategy is used.
type_name{: #graphql-queries-list-type_name }	atom		Override the type name returned by this query. Must be set if the read action has metadata that is not hidden via the show_metadata key.
description{: #graphql-queries-list-description }	String.t		The query description that gets shown in the Graphql schema. If not provided, the action description will be used.
metadata_names{: #graphql-queries-list-metadata_names }	keyword	[]	Name overrides for metadata fields on the read action.
metadata_types{: #graphql-queries-list-metadata_types }	keyword	[]	Type overrides for metadata fields on the read action.
show_metadata{: #graphql-queries-list-show_metadata }	list(atom)		The metadata attributes to show. Defaults to all.
as_mutation?{: #graphql-queries-list-as_mutation? }	boolean	false	Places the query in the mutations key instead. Not typically necessary, but is often paired with as_mutation?. See the the guide for more.
relay_id_translations{: #graphql-queries-list-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.
hide_inputs{: #graphql-queries-list-hide_inputs }	list(atom)	[]	A list of inputs to hide from the mutation.

Introspection

Target: AshGraphql.Resource.Query

graphql.queries.action

action name, action

Runs a generic action

Examples

action :check_status, :check_status

Arguments

Name	Type	Default	Docs
name{: #graphql-queries-action-name }	atom	:get	The name to use for the query.
action{: #graphql-queries-action-action .spark-required}	atom		The action to use for the query.

Options

Name	Type	Default	Docs
description{: #graphql-queries-action-description }	String.t		The description that gets shown in the Graphql schema. If not provided, the action description will be used.
hide_inputs{: #graphql-queries-action-hide_inputs }	list(atom)	[]	Inputs to hide in the mutation/query
relay_id_translations{: #graphql-queries-action-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.

Introspection

Target: AshGraphql.Resource.Action

graphql.mutations

Mutations (create/update/destroy actions) to expose for the resource.

Nested DSLs

• create
• update
• destroy
• action

Examples

mutations do
  create :create_post, :create
  update :update_post, :update
  destroy :destroy_post, :destroy
end

graphql.mutations.create

create name, action

A mutation to create a record

Examples

create :create_post, :create

Arguments

Name	Type	Default	Docs
name{: #graphql-mutations-create-name }	atom	:get	The name to use for the mutation.
action{: #graphql-mutations-create-action .spark-required}	atom		The action to use for the mutation.

Options

Name	Type	Default	Docs
description{: #graphql-mutations-create-description }	String.t		The mutation description that gets shown in the Graphql schema. If not provided, the action description will be used.
upsert?{: #graphql-mutations-create-upsert? }	boolean	false	Whether or not to use the upsert?: true option when calling YourDomain.create/2.
upsert_identity{: #graphql-mutations-create-upsert_identity }	atom	false	Which identity to use for the upsert
modify_resolution{: #graphql-mutations-create-modify_resolution }	mfa		An MFA that will be called with the resolution, the query, and the result of the action as the first three arguments. See the the guide for more.
hide_inputs{: #graphql-mutations-create-hide_inputs }	list(atom)	[]	A list of inputs to hide from the mutation.
relay_id_translations{: #graphql-mutations-create-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.

Introspection

Target: AshGraphql.Resource.Mutation

graphql.mutations.update

update name, action

A mutation to update a record

Examples

update :update_post, :update

Arguments

Name	Type	Default	Docs
name{: #graphql-mutations-update-name }	atom	:get	The name to use for the mutation.
action{: #graphql-mutations-update-action .spark-required}	atom		The action to use for the mutation.

Options

Name	Type	Default	Docs
identity{: #graphql-mutations-update-identity }	atom		The identity to use to fetch the record to be updated. Use false if no identity is required.
read_action{: #graphql-mutations-update-read_action }	atom		The read action to use to fetch the record to be updated. Defaults to the primary read action.
hide_inputs{: #graphql-mutations-update-hide_inputs }	list(atom)		A list of inputs to hide from the mutation.
relay_id_translations{: #graphql-mutations-update-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.

Introspection

Target: AshGraphql.Resource.Mutation

graphql.mutations.destroy

destroy name, action

A mutation to destroy a record

Examples

destroy :destroy_post, :destroy

Arguments

Name	Type	Default	Docs
name{: #graphql-mutations-destroy-name }	atom	:get	The name to use for the mutation.
action{: #graphql-mutations-destroy-action .spark-required}	atom		The action to use for the mutation.

Options

Name	Type	Default	Docs
read_action{: #graphql-mutations-destroy-read_action }	atom		The read action to use to fetch the record to be destroyed. Defaults to the primary read action.
identity{: #graphql-mutations-destroy-identity }	atom		The identity to use to fetch the record to be destroyed. Use false if no identity is required.
hide_inputs{: #graphql-mutations-destroy-hide_inputs }	list(atom)		A list of inputs to hide from the mutation.
relay_id_translations{: #graphql-mutations-destroy-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.

Introspection

Target: AshGraphql.Resource.Mutation

graphql.mutations.action

action name, action

Runs a generic action

Examples

action :check_status, :check_status

Arguments

Name	Type	Default	Docs
name{: #graphql-mutations-action-name }	atom	:get	The name to use for the query.
action{: #graphql-mutations-action-action .spark-required}	atom		The action to use for the query.

Options

Name	Type	Default	Docs
description{: #graphql-mutations-action-description }	String.t		The description that gets shown in the Graphql schema. If not provided, the action description will be used.
hide_inputs{: #graphql-mutations-action-hide_inputs }	list(atom)	[]	Inputs to hide in the mutation/query
relay_id_translations{: #graphql-mutations-action-relay_id_translations }	keyword	[]	A keyword list indicating arguments or attributes that have to be translated from global Relay IDs to internal IDs. See the Relay guide for more.

Introspection

Target: AshGraphql.Resource.Action

graphql.subscriptions

Subscriptions (notifications) to expose for the resource.

Nested DSLs

• subscribe

Examples

subscriptions do
  subscribe :bucket_created do
    actions :create
    read_action :read
  end
end

Options

Name	Type	Default	Docs
pubsub{: #graphql-subscriptions-pubsub .spark-required}	module		The pubsub module to use for the subscription

graphql.subscriptions.subscribe

subscribe name

A subscription to listen for changes on the resource

Examples

subscribe :post_created do
  action_types(:create)
end

Arguments

Name	Type	Default	Docs
name{: #graphql-subscriptions-subscribe-name }	atom		The name to use for the subscription.

Options

Name	Type	Default	Docs
actor{: #graphql-subscriptions-subscribe-actor }	(any -> any) | module		The actor to use for authorization.
actions{: #graphql-subscriptions-subscribe-actions }	list(atom) | atom		The create/update/destroy actions the subsciption should listen to.
action_types{: #graphql-subscriptions-subscribe-action_types }	list(atom) | atom		The type of actions the subsciption should listen to.
read_action{: #graphql-subscriptions-subscribe-read_action }	atom		The read action to use for reading data
hide_inputs{: #graphql-subscriptions-subscribe-hide_inputs }	list(atom)	[]	A list of inputs to hide from the subscription, usable if the read action has arguments.

Introspection

Target: AshGraphql.Resource.Subscription

graphql.managed_relationships

Generates input objects for manage_relationship arguments on resource actions.

Nested DSLs

• managed_relationship

Examples

managed_relationships do
  manage_relationship :create_post, :comments
end

Options

Name	Type	Default	Docs
auto?{: #graphql-managed_relationships-auto? }	boolean	true	Automatically derive types for all arguments that have a manage_relationship call change.

graphql.managed_relationships.managed_relationship

managed_relationship action, argument

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, :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

Since managed relationships can ultimately call multiple actions, there is the possibility of field type conflicts. Use the types option to determine the type of fields and remove the conflict warnings.

For non_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 pass nil as the type.

Arguments

Name	Type	Default	Docs
action{: #graphql-managed_relationships-managed_relationship-action }	atom		The action that accepts the argument
argument{: #graphql-managed_relationships-managed_relationship-argument .spark-required}	atom		The argument for which an input object should be derived.

Options

Name	Type	Default	Docs
lookup_with_primary_key?{: #graphql-managed_relationships-managed_relationship-lookup_with_primary_key? }	boolean		If the managed_relationship has on_lookup behavior, this option determines whether or not the primary key is provided in the input object for looking up.
lookup_identities{: #graphql-managed_relationships-managed_relationship-lookup_identities }	list(atom)		Determines which identities are provided in the input object for looking up, if there is on_lookup behavior. Defalts to the use_identities option.
type_name{: #graphql-managed_relationships-managed_relationship-type_name }	atom		The name of the input object that will be derived. Defaults to <action_type>_<resource>_<argument_name>_input
types{: #graphql-managed_relationships-managed_relationship-types }	any		A keyword list of field names to their graphql type identifiers.
ignore?{: #graphql-managed_relationships-managed_relationship-ignore? }	boolean	false	Use this to ignore a given managed relationship, preventing auto? true from deriving a type for it.

Introspection

Target: AshGraphql.Resource.ManagedRelationship

<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>