<!--
This file was generated by Spark. Do not edit it by hand.
-->
# 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`](#graphql-type){: #graphql-type .spark-required} | `atom` |  | The type to use for this entity in the graphql schema |
| [`derive_filter?`](#graphql-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?){: #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?){: #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){: #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. |
| [`field_names`](#graphql-field_names){: #graphql-field_names } | `keyword` |  | A keyword list of name overrides for attributes. |
| [`hide_fields`](#graphql-hide_fields){: #graphql-hide_fields } | `list(atom)` |  | A list of attributes to hide from the api |
| [`argument_names`](#graphql-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){: #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){: #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){: #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. |
| [`primary_key_delimiter`](#graphql-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){: #graphql-depth_limit } | `integer` |  | A simple way to prevent massive queries. |
| [`generate_object?`](#graphql-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){: #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. |


## 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
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#graphql-queries-get-name){: #graphql-queries-get-name } | `atom` | `:get` | The name to use for the query. |
| [`action`](#graphql-queries-get-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){: #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?){: #graphql-queries-get-allow_nil? } | `boolean` | `true` | Whether or not the action can return nil. |
| [`modify_resolution`](#graphql-queries-get-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](/documentation/topics/modifying-the-resolution.html) for more. |
| [`type_name`](#graphql-queries-get-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. |
| [`metadata_names`](#graphql-queries-get-metadata_names){: #graphql-queries-get-metadata_names } | `keyword` | `[]` | Name overrides for metadata fields on the read action. |
| [`metadata_types`](#graphql-queries-get-metadata_types){: #graphql-queries-get-metadata_types } | `keyword` | `[]` | Type overrides for metadata fields on the read action. |
| [`show_metadata`](#graphql-queries-get-show_metadata){: #graphql-queries-get-show_metadata } | `list(atom)` |  | The metadata attributes to show. Defaults to all. |
| [`as_mutation?`](#graphql-queries-get-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](/documentation/topics/modifying-the-resolution.html) for more. |
| [`relay_id_translations`](#graphql-queries-get-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) 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
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#graphql-queries-read_one-name){: #graphql-queries-read_one-name } | `atom` | `:get` | The name to use for the query. |
| [`action`](#graphql-queries-read_one-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?){: #graphql-queries-read_one-allow_nil? } | `boolean` | `true` | Whether or not the action can return nil. |
| [`type_name`](#graphql-queries-read_one-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. |
| [`metadata_names`](#graphql-queries-read_one-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){: #graphql-queries-read_one-metadata_types } | `keyword` | `[]` | Type overrides for metadata fields on the read action. |
| [`show_metadata`](#graphql-queries-read_one-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?){: #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](/documentation/topics/modifying-the-resolution.html) for more. |
| [`relay_id_translations`](#graphql-queries-read_one-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) 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
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#graphql-queries-list-name){: #graphql-queries-list-name } | `atom` | `:get` | The name to use for the query. |
| [`action`](#graphql-queries-list-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?){: #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](/documentation/topics/relay.html) for more. |
| [`type_name`](#graphql-queries-list-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. |
| [`metadata_names`](#graphql-queries-list-metadata_names){: #graphql-queries-list-metadata_names } | `keyword` | `[]` | Name overrides for metadata fields on the read action. |
| [`metadata_types`](#graphql-queries-list-metadata_types){: #graphql-queries-list-metadata_types } | `keyword` | `[]` | Type overrides for metadata fields on the read action. |
| [`show_metadata`](#graphql-queries-list-show_metadata){: #graphql-queries-list-show_metadata } | `list(atom)` |  | The metadata attributes to show. Defaults to all. |
| [`as_mutation?`](#graphql-queries-list-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](/documentation/topics/modifying-the-resolution.html) for more. |
| [`relay_id_translations`](#graphql-queries-list-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) 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 |
|------|------|---------|------|
| [`name`](#graphql-queries-action-name){: #graphql-queries-action-name } | `atom` | `:get` | The name to use for the query. |
| [`action`](#graphql-queries-action-action){: #graphql-queries-action-action .spark-required} | `atom` |  | The action to use for the query. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`relay_id_translations`](#graphql-queries-action-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) for more. |


### 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
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#graphql-mutations-create-name){: #graphql-mutations-create-name } | `atom` | `:get` | The name to use for the mutation. |
| [`action`](#graphql-mutations-create-action){: #graphql-mutations-create-action .spark-required} | `atom` |  | The action to use for the mutation. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`upsert?`](#graphql-mutations-create-upsert?){: #graphql-mutations-create-upsert? } | `boolean` | `false` | Whether or not to use the `upsert?: true` option when calling `YourApi.create/2`. |
| [`upsert_identity`](#graphql-mutations-create-upsert_identity){: #graphql-mutations-create-upsert_identity } | `atom` | `false` | Which identity to use for the upsert |
| [`modify_resolution`](#graphql-mutations-create-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](/documentation/topics/modifying-the-resolution.html) for more. |
| [`relay_id_translations`](#graphql-mutations-create-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) 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
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#graphql-mutations-update-name){: #graphql-mutations-update-name } | `atom` | `:get` | The name to use for the mutation. |
| [`action`](#graphql-mutations-update-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){: #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){: #graphql-mutations-update-read_action } | `atom` |  | The read action to use to fetch the record to be updated. Defaults to the primary read action. |
| [`relay_id_translations`](#graphql-mutations-update-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) for more. |


### Introspection

Target: `AshGraphql.Resource.Mutation`

## graphql.mutations.destroy
```elixir
destroy name, action
```


A mutation to destroy a record


### Examples
```
destroy :destroy_post, :destroy
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#graphql-mutations-destroy-name){: #graphql-mutations-destroy-name } | `atom` | `:get` | The name to use for the mutation. |
| [`action`](#graphql-mutations-destroy-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){: #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){: #graphql-mutations-destroy-identity } | `atom` |  | The identity to use to fetch the record to be destroyed. Use `false` if no identity is required. |
| [`relay_id_translations`](#graphql-mutations-destroy-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) for more. |


### 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 |
|------|------|---------|------|
| [`name`](#graphql-mutations-action-name){: #graphql-mutations-action-name } | `atom` | `:get` | The name to use for the query. |
| [`action`](#graphql-mutations-action-action){: #graphql-mutations-action-action .spark-required} | `atom` |  | The action to use for the query. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`relay_id_translations`](#graphql-mutations-action-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](/documentation/topics/relay.md#translating-relay-global-ids-passed-as-arguments) for more. |


### 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?`](#graphql-managed_relationships-auto?){: #graphql-managed_relationships-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.


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`action`](#graphql-managed_relationships-managed_relationship-action){: #graphql-managed_relationships-managed_relationship-action } | `atom` |  | The action that accepts the argument |
| [`argument`](#graphql-managed_relationships-managed_relationship-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?){: #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){: #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){: #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){: #graphql-managed_relationships-managed_relationship-types } | `any` |  | A keyword list of field names to their graphql type identifiers. |


### Introspection

Target: `AshGraphql.Resource.ManagedRelationship`


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