absinthe v1.3.2 Absinthe.Schema.Notation

This module contains macros used to build GraphQL types.

See Absinthe.Schema for a rough overview of schema building from scratch.

Summary

Functions

Add an argument

Mark a field as deprecated

Defines a description

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

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

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

Defines the types possible under a union type

Defines a value possible under an enum type

Functions

arg(identifier, attrs) (macro)

Add an argument.

See arg/3

arg(identifier, type, attrs) (macro)

Add an argument.

Placement

Allowed under: directive field

Examples

field do
  arg :size, :integer
  arg :name, :string, description: "The desired name"
end
complexity(func_ast) (macro)
deprecate(msg) (macro)

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
description(text) (macro)

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

directive(identifier, attrs \\ [], list) (macro)

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
enum(identifier, attrs) (macro)

Defines an enum type

See enum/3

enum(identifier, attrs, list) (macro)

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
expand(func_ast) (macro)

Define the expansion for a directive

Placement

Allowed under: directive

field(identifier, attrs) (macro)

Defines a GraphQL field

See field/4

field(identifier, attrs, attrs) (macro)

Defines a GraphQL field

See field/4

field(identifier, type, attrs, list) (macro)

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(type_name, opts \\ []) (macro)

Import fields from another object

import_types(type_module_ast) (macro)

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
input_object(identifier, attrs \\ [], list) (macro)

Defines an input object

See Absinthe.Type.InputObject

Placement

Top level in module.

Examples

input_object :contact_input do
  field :email, non_null(:string)
end
instruction(func_ast) (macro)

Calculate the instruction for a directive

Placement

Allowed under: directive

interface(identifier) (macro)

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
interface(identifier, attrs \\ [], list) (macro)

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
interfaces(ifaces) (macro)

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
is_type_of(func_ast) (macro)

Placement

Allowed under: object

list_of(type) (macro)

Marks a type reference as a list of the given type

See field/3 for examples

meta(key, value) (macro)

Defines a metadata key/value pair for a custom type.

middleware(new_middleware, opts \\ []) (macro)
non_null(type) (macro)

Marks a type reference as non null

See field/3 for examples

object(identifier, attrs \\ [], list) (macro)

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
on(ast_node) (macro)

Declare a directive as operating an a AST node type

See directive/2

Placement

Allowed under: directive

parse(func_ast) (macro)

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

record_object!(env, identifier, attrs, block)
recordable!(env, usage, kw_rules, opts \\ [])
resolve(func_ast) (macro)

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
resolve_type(func_ast) (macro)

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
scalar(identifier, attrs) (macro)

Defines a scalar type

See scalar/3

scalar(identifier, attrs, list) (macro)

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
serialize(func_ast) (macro)

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

types(types) (macro)

Defines the types possible under a union type

See union/3

Placement

Allowed under: union

union(identifier, attrs \\ [], list) (macro)

Defines a union type

See Absinthe.Type.Union

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
value(identifier, raw_attrs \\ []) (macro)

Defines a value possible under an enum type

See enum/3

Placement

Allowed under: enum