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

dsl-documentation

DSL Documentation

index

Index

• graphql
  • queries
    • get
    • read_one
    • list
  • mutations
    • create
    • update
    • destroy
  • managed_relationships
    • managed_relationship

docs

Docs

graphql

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

Imports:

• AshGraphql.Resource.Helpers

• :type (atom/0) - Required. The type to use for this entity in the graphql schema

• :derive_filter? (boolean/0) - Set to false to disable the automatic generation of a filter input for read actions. The default value is true.

• :derive_sort? (boolean/0) - Set to false to disable the automatic generation of a sort input for read actions. The default value is true.

• :encode_primary_key? (boolean/0) - 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 The default value is true.

• :relationships (list of atom/0) - 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/0) - A keyword list of name overrides for attributes.

• :hide_fields (list of atom/0) - A list of attributes to hide from the api

• :argument_names (keyword/0) - A nested keyword list of action names, to argument name remappings. i.e create: [arg_name: :new_name]

• :keyset_field (atom/0) - If set, the keyset will be displayed on all read actions in this field.
  It will always be nil unless at least one of the read actions on a resource uses keyset pagination. It will also be nil on any mutation results.

• :attribute_types (keyword/0) - 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/0) - 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/0) - If a composite primary key exists, this can be set to determine delimiter used in the id field value. The default value is "~".

• :depth_limit (integer/0) - A simple way to prevent massive queries.

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

• :filterable_fields (list of atom/0) - A list of fields that are allowed to be filtered on. Defaults to all filterable fields for which a GraphQL type can be created.

queries

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

Examples:

get :get_post, :read

• :identity (atom/0) - The identity to use for looking up the record. Pass false to not use an identity.

• :allow_nil? (boolean/0) - 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.

• :name (atom/0) - The name to use for the query. The default value is :get.

• :action (atom/0) - Required. The action to use for the query.

• :type_name (atom/0) - Override the type name returned by this query. Must be set if the read action has metadata.
  To ignore any action metadata, set this to the same type the resource uses, or set show_metadata to []. To show metadata in the response, choose a new name here, like :user_with_token to get a response type that includes the additional fields.

• :metadata_names (keyword/0) - Name overrides for metadata fields on the read action. The default value is [].

• :metadata_types (keyword/0) - Type overrides for metadata fields on the read action. The default value is [].

• :show_metadata (list of atom/0) - The metadata attributes to show. Defaults to all.

• :as_mutation? (boolean/0) - 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

Examples:

read_one :current_user, :current_user

• :allow_nil? (boolean/0) - Whether or not the action can return nil. The default value is true.

• :name (atom/0) - The name to use for the query. The default value is :get.

• :action (atom/0) - Required. The action to use for the query.

• :type_name (atom/0) - Override the type name returned by this query. Must be set if the read action has metadata.
  To ignore any action metadata, set this to the same type the resource uses, or set show_metadata to []. To show metadata in the response, choose a new name here, like :user_with_token to get a response type that includes the additional fields.

• :metadata_names (keyword/0) - Name overrides for metadata fields on the read action. The default value is [].

• :metadata_types (keyword/0) - Type overrides for metadata fields on the read action. The default value is [].

• :show_metadata (list of atom/0) - The metadata attributes to show. Defaults to all.

• :as_mutation? (boolean/0) - 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.

list

A query to fetch a list of records

Examples:

list :list_posts, :read

list :list_posts_paginated, :read, relay?: true

• :relay? (boolean/0) - 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.

• :name (atom/0) - The name to use for the query. The default value is :get.

• :action (atom/0) - Required. The action to use for the query.

• :type_name (atom/0) - Override the type name returned by this query. Must be set if the read action has metadata.
  To ignore any action metadata, set this to the same type the resource uses, or set show_metadata to []. To show metadata in the response, choose a new name here, like :user_with_token to get a response type that includes the additional fields.

• :metadata_names (keyword/0) - Name overrides for metadata fields on the read action. The default value is [].

• :metadata_types (keyword/0) - Type overrides for metadata fields on the read action. The default value is [].

• :show_metadata (list of atom/0) - The metadata attributes to show. Defaults to all.

• :as_mutation? (boolean/0) - 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.

mutations

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

Examples:

create :create_post, :create

• :name (atom/0) - The name to use for the mutation. The default value is :get.

• :action (atom/0) - Required. The action to use for the mutation.

• :upsert? (boolean/0) - Whether or not to use the upsert?: true option when calling YourApi.create/2. The default value is false.

• :upsert_identity (atom/0) - Which identity to use for the upsert 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

Examples:

update :update_post, :update

• :name (atom/0) - The name to use for the mutation. The default value is :get.

• :action (atom/0) - Required. The action to use for the mutation.

• :identity (atom/0) - 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 (atom/0) - 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

Examples:

destroy :destroy_post, :destroy

• :name (atom/0) - The name to use for the mutation. The default value is :get.

• :action (atom/0) - Required. The action to use for the mutation.

• :read_action (atom/0) - The read action to use to fetch the record to be destroyed. Defaults to the primary read action.

• :identity (atom/0) - 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

managed_relationships

Generates input objects for manage_relationship arguments on resource actions.

• managed_relationship

Examples:

managed_relationships do
  manage_relationship :create_post, :comments
end

• :auto? (boolean/0) - Automatically derive types for all arguments that have a manage_relationship call change.

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

• :argument (atom/0) - Required. The argument for which an input object should be derived.

• :action (atom/0) - The action that accepts the argument

• :lookup_with_primary_key? (boolean/0) - 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 (list of atom/0) - 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 (atom/0) - 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 (term/0) - 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.