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

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 the id 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 interface

• pagination over that resource will behave as a Connection. The default value is false.

  • :generate_object? - Whether or not to create the GraphQL object, this allows you to manually create the GraphQL object. The default value is true.

queries

Queries (read actions) to expose for the resource.

• get
• read_one
• list

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:

AshGraphql.Resource.Query

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 - The identity to use for looking up the record. Pass false to not use an identity.

• :allow_nil? - Whether or not the action can return nil. The default value is true.

• :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 set as_mutation? to true and represent this in your graphql as a mutation. See as_mutation? for more.

• :as_mutation? - Places the query in the mutations key instead. The use cases for this are likely very minimal.
  
  If you have a query that needs to modify the graphql context using modify_resolution, then you should likely set this as well. A simple example might be a log_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 of modify_resolution. Once in the context, you can see the guide referenced in modify_resolution for more on setting the session or a cookie with an auth token. The default value is false.

read_one

A query to fetch a record

Introspection Target:

AshGraphql.Resource.Query

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 is true.

list

A query to fetch a list of records

Introspection Target:

AshGraphql.Resource.Query

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.

• create
• update
• destroy

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:

AshGraphql.Resource.Mutation

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 the upsert?: true option when calling YourApi.create/2. The default value is false.

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

AshGraphql.Resource.Mutation

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), use false.

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

AshGraphql.Resource.Mutation

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), use false.

managed_relationships

Generates input objects for manage_relationship arguments on resource actions.

• managed_relationship

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 has on_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 no on_lookup.

• :lookup_identities - If the managed_relationship has on_lookup behavior, this option determines which identities are provided in the input object for looking up.
  
  This option is ignored if there is no on_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.
  
  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.