View Source GraphQLDocument (GraphQLDocument v0.1.0)
A utility for building GraphQL documents. (Strings that contain a GraphQL query/mutation.)
syntax
Syntax
GraphQLDocument.to_string
converts nested lists/keyword lists into the analogous
GraphQL syntax.
Simply write lists and keyword lists "as they look in GraphQL".
Let's take a look at some examples.
object-fields
Object Fields
To request a list of fields in an object, include them in a list:
[query: [
human: [:name, :height]
]]
GraphQLDocument.to_string/1
will take that Elixir structure and return
"""
query {
human {
name
height
}
}
"""
arguments
Arguments
When a field includes arguments, wrap the arguments and child fields in a tuple, like this:
{args, fields}
For example, GraphQLDocument.to_string/1
will take this Elixir structure
[query: [
human: {
[id: "1000"],
[:name, :height]
}
]]
and return this GraphQL document:
"""
query {
human(id: "1000") {
name
height
}
}
"""
Argument types and Enums
GraphQLDocument.to_string/1
will translate Elixir primitives into the
analogous GraphQL primitive type for arguments.
GraphQL enums can be expressed as an atom (e.g. FOOT
) or in a tuple
syntax, {:enum, "FOOT"}
.
For example:
[query: [
human: {
[id: "1000"],
[:name, height: {[unit: FOOT], []}]
}
]]
becomes
query {
human(id: "1000") {
name
height(unit: FOOT)
}
}
We can specify [unit: FOOT]
as [unit: {:enum, "FOOT"}]
, which
is useful for interpolating dynamic values into the query.
Expressing arguments without sub-fields
Notice the slightly complicated syntax above:
height: {[unit: FOOT], []}
The way to include arguments is in an
{args, fields}
tuple. So if a field has arguments but no sub-fields, put[]
where the sub-fields go.
nesting-fields
Nesting Fields
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:
# 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 like this:
[query: [
human: {
[id: "1000"],
[
:name,
:height,
friends: {
[olderThan: 30],
[:name, :height]
}
]
}
]]
query {
human(id: "1000") {
name
height
friends(olderThan: 30) {
name
height
}
}
}
aliases
Aliases
In order to name a field with an alias, follow the syntax below, where me
is the alias and user
is the field:
[query: [
me: {
:user
[id: 100],
[:name, :email]
}
]]
Which will emit this GraphQL document:
query {
me: user(id: 100) {
name
email
}
}
Link to this section Summary
Functions
Wraps an enum string value (such as user input from a form) into a
GraphQLDocument
-friendly tuple.
Generates GraphQL syntax from a nested Elixir keyword list.
Link to this section Functions
Wraps an enum string value (such as user input from a form) into a
GraphQLDocument
-friendly tuple.
example
Example
iex> GraphQLDocument.enum("soundex")
{:enum, "soundex"}
Generates GraphQL syntax from a nested Elixir keyword list.
example
Example
iex> GraphQLDocument.to_string(query: [user: {[id: 3], [:name, :age, :height, documents: [:filename, :url]]}])
"""
query {
user(id: 3) {
name
age
height
documents {
filename
url
}
}
}\
"""