absinthe v1.4.0-beta.1 Absinthe.Schema.Notation View Source
This module contains macros used to build GraphQL types.
See Absinthe.Schema
for a rough overview of schema building from scratch.
Link to this section Summary
Functions
Add an argument
Add an argument
Mark a field as deprecated
Defines a description
Defines a directive
Defines an enum type
Defines an enum type
Define the expansion for a directive
Defines a GraphQL field
Defines a GraphQL field
Defines a GraphQL field
Import fields from another object
Import types from another module
Defines an input object
Calculate the instruction for a directive
Declare an implemented interface for an object
Define an interface type
Declare implemented interfaces for an object
Marks a type reference as a list of the given type
Defines a metadata key/value pair for a custom type
Marks a type reference as non null
Define an object type
Declare a directive as operating an a AST node type
Defines a parse function for a scalar
type
Defines a resolve function for a field
Define a type resolver for a union or interface
Defines a scalar type
Define a scalar type
Defines a serialization function for a scalar
type
Set the topic function for a subscription field. See the subscription/2
macro
docs for details
Set a trigger for a subscription field
Defines the types possible under a union type
Defines a union type
Defines a value possible under an enum type
Link to this section Functions
Add an argument.
See arg/3
Add an argument.
Placement
Allowed under: directive
field
Examples
field do
arg :size, :integer
arg :name, :string, description: "The desired name"
end
Mark a field as deprecated
In most cases you can simply pass the deprecate: “message” attribute. However when using the block form of a field it can be nice to also use this macro.
Placement
Allowed under: field
Examples
field :foo, :string do
deprecate "Foo will no longer be supported"
end
This is how to deprecate other things
field :foo, :string do
arg :bar, :integer, deprecate: "This isn't supported either"
end
enum :colors do
value :red
value :blue, deprecate: "This isn't supported"
end
Defines a description
This macro adds a description to any other macro which takes a block.
Note that you can also specify a description by using @desc
above any item
that can take a description attribute.
Placement
Allowed under any block. Not allowed to be top level
Defines a directive
Placement
Top level in module.
Examples
directive :mydirective do
arg :if, non_null(:boolean), description: "Skipped when true."
on Language.FragmentSpread
on Language.Field
on Language.InlineFragment
instruction fn
%{if: true} ->
:skip
_ ->
:include
end
end
Defines an enum type
See enum/3
Defines an enum type
Placement
Top level in module.
Examples
Handling RED
, GREEN
, BLUE
values from the query document:
enum :color do
value :red
value :green
value :blue
end
A given query document might look like:
{
foo(color: RED)
}
Internally you would get an argument in elixir that looks like:
%{color: :red}
If your return value is an enum, it will get serialized out as:
{"color": "RED"}
You can provide custom value mappings. Here we use r
, g
, b
values:
enum :color do
value :red, as: "r"
value :green, as: "g"
value :blue, as: "b"
end
Defines a GraphQL field
See field/4
Defines a GraphQL field
See field/4
Defines a GraphQL field.
Placement
Allowed under: input_object
interface
object
query
, mutation
, and subscription
are
all objects under the covers, and thus you’ll find field
definitions under
those as well.
Examples
field :id, :id
field :age, :integer, description: "How old the item is"
field :name, :string do
description "The name of the item"
end
field :location, type: :location
Import fields from another object
Example
object :news_queries do
field :all_links, list_of(:link)
field :main_story, :link
end
object :admin_queries do
field :users, list_of(:user)
field :pending_posts, list_of(:post)
end
query do
import_fields :news_queries
import_fields :admin_queries
end
Import fields can also be used on objects created inside other modules that you have used import_types on.
defmodule MyApp.Schema.NewsTypes do
use Absinthe.Schema.Notation
object :news_queries do
field :all_links, list_of(:link)
field :main_story, :link
end
end
defmodule MyApp.Schema.Schema do
use Absinthe.Schema
import_types MyApp.Schema.NewsTypes
query do
import_fields :news_queries
# ...
end
end
Import types from another module
Very frequently your schema module will simply have the query
and mutation
blocks, and you’ll want to break out your other types into other modules. This
macro imports those types for use the current module
Placement
Top level in module.
Examples
import_types MyApp.Schema.Types
Defines an input object
Placement
Top level in module.
Examples
input_object :contact_input do
field :email, non_null(:string)
end
Declare an implemented interface for an object.
Adds an Absinthe.Type.Interface
to your schema.
See also interfaces/1
, which can be used for multiple interfaces,
and interface/3
, used to define interfaces themselves.
Examples
object :car do
interface :vehicle
# ...
end
Define an interface type.
Adds an Absinthe.Type.Interface
to your schema.
Also see interface/1
and interfaces/1
, which declare
that an object implements one or more interfaces.
Placement
Top level in module.
Examples
interface :vehicle do
field :wheel_count, :integer
end
object :rally_car do
field :wheel_count, :integer
interface :vehicle
end
Declare implemented interfaces for an object.
See also interface/1
, which can be used for one interface,
and interface/3
, used to define interfaces themselves.
Placement
Allowed under: object
Examples
object :car do
interfaces [:vehicle, :branded]
# ...
end
Marks a type reference as a list of the given type
See field/3
for examples
Defines a metadata key/value pair for a custom type.
Marks a type reference as non null
See field/3
for examples
Define an object type.
Adds an Absinthe.Type.Object
to your schema.
Placement
Top level in module.
Examples
Basic definition:
object :car do
# ...
end
Providing a custom name:
object :car, name: "CarType" do
# ...
end
Declare a directive as operating an a AST node type
See directive/2
Placement
Allowed under: directive
Defines a parse function for a scalar
type
The specified parse
function is used on incoming data to transform it into
an elixir datastructure.
It should return {:ok, value}
or {:error, reason}
Placement
Allowed under: scalar
Defines a resolve function for a field
Specify a 2 or 3 arity function to call when resolving a field.
You can either hard code a particular anonymous function, or have a function call that returns a 2 or 3 arity anonymous function. See examples for more information.
Note that when using a hard coded anonymous function, the function will not capture local variables.
3 Arity Functions
The first argument to the function is the parent entity.
{
user(id: 1) {
name
}
}
A resolution function on the name
field would have the result of the user(id: 1)
field
as its first argument. Top level fields have the root_value
as their first argument.
Unless otherwise specified, this defaults to an empty map.
The second argument to the resolution function is the field arguments. The final
argument is an Absinthe.Resolution
struct, which includes information like
the context
and other execution data.
2 Arity Function
Exactly the same as the 3 arity version, but without the first argument (the parent entity)
Placement
Allowed under: field
Examples
query do
field :person, :person do
resolve &Person.resolve/2
end
end
query do
field :person, :person do
resolve fn %{id: id}, _ ->
{:ok, Person.find(id)}
end
end
end
query do
field :person, :person do
resolve lookup(:person)
end
end
def lookup(:person) do
fn %{id: id}, _ ->
{:ok, Person.find(id)}
end
end
Define a type resolver for a union or interface.
See also:
Placement
Allowed under: interface
union
Examples
interface :entity do
# ...
resolve_type fn
%{employee_count: _}, _ ->
:business
%{age: _}, _ ->
:person
end
end
Defines a scalar type
See scalar/3
Define a scalar type
A scalar type requires parse/1
and serialize/1
functions.
Placement
Top level in module.
Examples
scalar :time, description: "ISOz time" do
parse &Timex.parse(&1.value, "{ISOz}")
serialize &Timex.format!(&1, "{ISOz}")
end
Defines a serialization function for a scalar
type
The specified serialize
function is used on outgoing data. It should simply
return the desired external representation.
Placement
Allowed under: scalar
Set the topic function for a subscription field. See the subscription/2
macro
docs for details
Set a trigger for a subscription field.
It accepts one or more mutation field names, and can be called more than once.
mutation do
field :gps_event, :gps_event
field :user_checkin, :user
end
subscription do
field :location_update, :user do
arg :user_id, non_null(:id)
topic fn args ->
args.user_id
end
trigger :gps_event, topic: fn event ->
event.user_id
end
trigger :user_checkin, topic: fn user ->
user.id
end
end
end
Trigger functions are only called once per event, so database calls within them do not present a significant burden.
See the subscription/2
macro docs for additional details
Defines the types possible under a union type
See union/3
Placement
Allowed under: union
Defines a union type
Placement
Top level in module.
Examples
union :search_result do
description "A search result"
types [:person, :business]
resolve_type fn
%Person{}, _ -> :person
%Business{}, _ -> :business
end
end
Defines a value possible under an enum type
See enum/3
Placement
Allowed under: enum