# 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](#graphql-queries) * get * read_one * list * action * [mutations](#graphql-mutations) * create * update * destroy * action * [managed_relationships](#graphql-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 *	atom		The type to use for this entity in the graphql schema
derive_filter?	boolean	true	Set to false to disable the automatic generation of a filter input for read actions.
derive_sort?	boolean	true	Set to false to disable the automatic generation of a sort input for read actions.
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	list(atom)		A list of relationships to include on the created type. Defaults to all public relationships where the destination defines a graphql type.
field_names	Keyword.t		A keyword list of name overrides for attributes.
hide_fields	list(atom)		A list of attributes to hide from the api
argument_names	Keyword.t		A nested keyword list of action names, to argument name remappings. i.e `create: [arg_name: :new_name]`
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	Keyword.t		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	Keyword.t		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.
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	integer		A simple way to prevent massive queries.
generate_object?	boolean	true	Whether or not to create the GraphQL object, this allows you to manually create the GraphQL object.
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.

## graphql.queries Queries (read actions) to expose for the resource. ### Nested DSLs * [get](#graphql-queries-get) * [read_one](#graphql-queries-read_one) * [list](#graphql-queries-list) * [action](#graphql-queries-action) ### Examples ``` queries do get :get_post, :read read_one :current_user, :current_user list :list_posts, :read end ``` ## graphql.queries.get ```elixir get name, action ``` A query to fetch a record by primary key ### Examples ``` get :get_post, :read ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to use for the query.
identity	atom		The identity to use for looking up the record. Pass `false` to not use an identity.
allow_nil?	boolean	true	Whether or not the action can return nil.
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](/documentation/topics/modifying-the-resolution.html) for more.
name	atom	:get	The name to use for the query.
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.
metadata_names	Keyword.t	[]	Name overrides for metadata fields on the read action.
metadata_types	Keyword.t	[]	Type overrides for metadata fields on the read action.
show_metadata	list(atom)		The metadata attributes to show. Defaults to all.
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](/documentation/topics/modifying-the-resolution.html) for more.

### Introspection Target: `AshGraphql.Resource.Query` ## graphql.queries.read_one ```elixir read_one name, action ``` A query to fetch a record ### Examples ``` read_one :current_user, :current_user ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to use for the query.
allow_nil?	boolean	true	Whether or not the action can return nil.
name	atom	:get	The name to use for the query.
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.
metadata_names	Keyword.t	[]	Name overrides for metadata fields on the read action.
metadata_types	Keyword.t	[]	Type overrides for metadata fields on the read action.
show_metadata	list(atom)		The metadata attributes to show. Defaults to all.
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](/documentation/topics/modifying-the-resolution.html) for more.

### Introspection Target: `AshGraphql.Resource.Query` ## graphql.queries.list ```elixir list name, action ``` A query to fetch a list of records ### Examples ``` list :list_posts, :read ``` ``` list :list_posts_paginated, :read, relay?: true ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to use for the query.
relay?	boolean	false	If true, the graphql queries/resolvers for this resource will be built to honor the relay specification. See [the relay guide](/documentation/topics/relay.html) for more.
name	atom	:get	The name to use for the query.
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.
metadata_names	Keyword.t	[]	Name overrides for metadata fields on the read action.
metadata_types	Keyword.t	[]	Type overrides for metadata fields on the read action.
show_metadata	list(atom)		The metadata attributes to show. Defaults to all.
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](/documentation/topics/modifying-the-resolution.html) for more.

### Introspection Target: `AshGraphql.Resource.Query` ## graphql.queries.action ```elixir action name, action ``` Runs a generic action ### Examples ``` action :check_status, :check_status ``` ### Arguments

Name	Type	Default	Docs
action *	atom		The action to use for the query.

### Options

Name	Type	Default	Docs
name	atom	:get	The name to use for the query.

### Introspection Target: `AshGraphql.Resource.Action` ## graphql.mutations Mutations (create/update/destroy actions) to expose for the resource. ### Nested DSLs * [create](#graphql-mutations-create) * [update](#graphql-mutations-update) * [destroy](#graphql-mutations-destroy) * [action](#graphql-mutations-action) ### Examples ``` mutations do create :create_post, :create update :update_post, :update destroy :destroy_post, :destroy end ``` ## graphql.mutations.create ```elixir create name, action ``` A mutation to create a record ### Examples ``` create :create_post, :create ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to use for the mutation.
name	atom	:get	The name to use for the mutation.
upsert?	boolean	false	Whether or not to use the `upsert?: true` option when calling `YourApi.create/2`.
upsert_identity	atom	false	Which identity to use for the upsert
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](/documentation/topics/modifying-the-resolution.html) for more.

### Introspection Target: `AshGraphql.Resource.Mutation` ## graphql.mutations.update ```elixir update name, action ``` A mutation to update a record ### Examples ``` update :update_post, :update ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to use for the mutation.
name	atom	:get	The name to use for the mutation.
identity	atom		The identity to use to fetch the record to be updated. Use `false` if no identity is required.
read_action	atom		The read action to use to fetch the record to be updated. Defaults to the primary read action.

### Introspection Target: `AshGraphql.Resource.Mutation` ## graphql.mutations.destroy ```elixir destroy name, action ``` A mutation to destroy a record ### Examples ``` destroy :destroy_post, :destroy ``` ### Options

Name	Type	Default	Docs
action *	atom		The action to use for the mutation.
name	atom	:get	The name to use for the mutation.
read_action	atom		The read action to use to fetch the record to be destroyed. Defaults to the primary read action.
identity	atom		The identity to use to fetch the record to be destroyed. Use `false` if no identity is required.

### Introspection Target: `AshGraphql.Resource.Mutation` ## graphql.mutations.action ```elixir action name, action ``` Runs a generic action ### Examples ``` action :check_status, :check_status ``` ### Arguments

Name	Type	Default	Docs
action *	atom		The action to use for the query.

### Options

Name	Type	Default	Docs
name	atom	:get	The name to use for the query.

### Introspection Target: `AshGraphql.Resource.Action` ## graphql.managed_relationships Generates input objects for `manage_relationship` arguments on resource actions. ### Nested DSLs * [managed_relationship](#graphql-managed_relationships-managed_relationship) ### Examples ``` managed_relationships do manage_relationship :create_post, :comments end ``` ### Options

Name	Type	Default	Docs
auto?	boolean		Automatically derive types for all arguments that have a `manage_relationship` call change.

## graphql.managed_relationships.managed_relationship ```elixir 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: ```elixir 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 ```elixir 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. ### Options

Name	Type	Default	Docs
argument *	atom		The argument for which an input object should be derived.
action	atom		The action that accepts the argument
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	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	atom		The name of the input object that will be derived. Defaults to `___input`
types	`any`		A keyword list of field names to their graphql type identifiers.

### Introspection Target: `AshGraphql.Resource.ManagedRelationship`