Builds GraphQL Documents from simple Elixir data structures.

These functions take Elixir data in the same structure as GraphQL and return the analogous GraphQL Document as a String.

• GraphQLDocument.query/2
• GraphQLDocument.mutation/2
• GraphQLDocument.subscription/2

Using these abilities, developers can generate GraphQL queries programmatically. GraphQLDocument can be used to create higher-level DSLs for writing GraphQL queries.

getting-started

Getting Started

Elixir & GraphQL Code Snippets

Each Elixir code snippet is immediately followed by the GraphQL that it will produce.

All functions called in the code snippets below are in GraphQLDocument. (import GraphQLDocument to directly use them.)

object-fields

Object Fields

To request a list of fields in an object, include them in a list.

query([
  human: [
    :name,
    :height
  ]
])

query {
  human {
    name
    height
  }
}

arguments

Arguments

Wrap arguments along with child fields in a tuple.

{args, fields}

query(
  human: {[id: "1000"], [
    :name,
    :height
  ]}
)

query {
  human(id: "1000") {
    name
    height
  }
}

Argument types and Enums

Elixir primitives (numbers, strings, lists, booleans, etc.) are translated into the analogous GraphQL primitive.

Enums are expressed with atoms, like MY_ENUM, :MY_ENUM, or :"MY_ENUM"

query(
  human: {[id: "1000"], [
    :name,
    height: {[unit: FOOT], []}
  ]}
)

query {
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}

Expressing Arguments Without Sub-fields

Notice the slightly complicated syntax above: height: {[unit: FOOT], []}

Since args can be expressed in {args, fields} tuple, we put [] where the sub-fields go because there are no sub-fields.

This can also be expressed as height: field(args: [unit: FOOT]). See field/1.

mixing-lists-and-keyword-lists

Mixing Lists and Keyword Lists

Since GraphQL supports a theoretically infinite amount of nesting, you can also nest as much as needed in the Elixir structure.

Furthermore, we can take advantage of Elixir's syntax feature that allows a regular list to be "mixed" with a keyword list. (The keyword pairs must be at the end.)

# Elixir allows lists with a Keyword List as the final members
[
  :name,
  :height,
  friends: [
    :name,
    :age
  ]
]

Using this syntax, we can build a nested structure where we select primitive fields (like :name below) alongside object fields (like :friends).

query(
  human: {[id: "1000"], [
    :name,
    :height,
    friends: {[olderThan: 30], [
      :name,
      :height
    ]}
  ]}
)

query {
  human(id: "1000") {
    name
    height
    friends(olderThan: 30) {
      name
      height
    }
  }
}

variables

Variables

To express a variable as a value, use {:var, var_name} syntax or the var/1 function.

The variable definition is passed as an option to query/2, mutation/2, or subscription/2.

Variable types can take the form Int, {Int, null: false}, or {Int, default: 1}.

query(
  [
    user: {
      [id: var(:myId)],
      [
        :name,
        friends: {
          [type: {:var, :friendType}],
          [:name]
        }
      ]
    }
  ],
  variables: [
    myId: {Int, null: false},
    friendType: {String, default: "best"}
  ]
)

query ($myId: Int!, $friendType: String = "best") {
  user(id: $myId) {
    name
    friends(type: $friendType) {
      name
    }
  }
}

fragments

Fragments

To express a fragment, use the :... atom as the field name, similar to how you would in GraphQL.

The fragment definition is passed as an option to query/2, mutation/2, or subscription/2.

Inline fragments and fragment definitions use the on/1 function to specify the type condition.

query(
  [
    self: [
     ...: {
       on(User),
       [skip: [if: true]],
       [:password, :passwordHash]
     },
     friends: [
       ...: :friendFields
     ]
   ]
  ],
  fragments: [
    friendFields: {on(User), [
      :id,
      :name,
      profilePic: field(args: [size: 50])
    ]}
  ]
)

query {
  self {
    ... on User @skip(if: true) {
      password
      passwordHash
    }
    friends(first: 10) {
      ...friendFields
    }
  }
}

fragment friendFields on User {
  id
  name
  profilePic(size: 50)
}

features-that-require-field

Features That Require field()

The field/1 and field/2 functions are required in order to express Aliases and Directives.

aliases

Aliases

Express an alias by putting the alias in place of the field name, and pass the field name as the first argument to field/2.

In the example below, me is the alias and user is the field.

Spot the Keyword List

args: and select: below are members of an "invisible" keyword list using Elixir's call syntax.

query(
  me: field(
    :user,
    args: [id: 100],
    select: [:name, :email]
  )
)

query {
  me: user(id: 100) {
    name
    email
  }
}

directives

Directives

Express a directive by passing directives: to field/1 or field/2.

A directive can be a single name (as an atom or string) or a tuple in {name, args} format.

query(
  self: field(
    directives: [:debug, log: [level: "warn"]]
    select: [:name, :email]
  )
)

query {
  self @debug @log(level: "warn") {
    name
    email
  }
}

not-yet-supported-features

Not-yet-supported features

GraphQLDocument does not currently have the ability to generate Type System definitions, although they technically belong in a Document.