Erlang GraphQL Tutorial

The tutorial you are now reading isn’t really a tutorial per se where you type in stuff and see the output. There is a bit too much code for that kind of exposition. Rather, the tutorial describes a specific project implemented by means of the GraphQL system. You can use the ideas herein to build your own.

There are examples of how things are built however, so you may be able to follow along and check out the construction of the system as a whole. Apart from being a small self-contained functional GraphQL project, it is also a small self-contained functional rebar3 project. So there’s that.

Some Erlang knowledge is expected for reading this guide. General Erlang concept will not be explained, but assumed to be known. Some Mnesia knowledge will also help a bit in understanding what is going on, though if you know anything about databases in general, that is probably enough. Furthermore, some knowledge of the web in general is assumed. We don’t cover the intricacies of HTTP 1.1 or HTTP/2 for instance.

This tutorial uses a couple of dependencies:

The GraphQL system should run on any system which can run Erlang. The library does not use any special tooling, nor does it make any assumptions about the environment. If Erlang runs on your platform, chances are that GraphQL will too.

The official repository location is

https://github.com/shopgun/graphql-erlang-tutorial

If you have comments on the document or corrections, please open an Issue in the above repository on the thing that is missing. Also, feel free to provide pull requests against the code itself.

Things we are particularly interested in:

Copyright © 2017 ShopGun.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

The first query we will run requests a given Planet from the system. This query follows a set of rules, the Relay Modern GraphQL conventions. These conventions are formed by Facebook as part of their Relay Modern system. It defines a common set of functionality on top of the GraphQL system which clients can rely on.

In particular, our first query uses the rules of Object Identification which is a way to load an object for which you already know its identity. A more complete exposition of the conventions are in the section Relay Modern, but here we skip the introduction for the sake of brevity:

If you enter this in the GraphiQL left window and press the “Run” button, you should get the following response:

Note how the response reflects the structure of the query. This is a powerful feature of GraphQL since it allows you to build up queries client side and get deterministic results based off of your query-structure.

Let us look at a far more intricate query. In this query, we will also request a planet, but then we will ask “what films does this planet appear in?” and we will ask “Who are the residents on the planet?”--who has the planet as their homeworld?.

To do this, we use pagination. We ask for the first 2 films and the first 3 residents. We also ask for the relevant meta-data of the connections as we are here:

The fragment parts allows your queries to re-use different subsets of a larger query again and again. We use this here to show off that capability of GraphQL. The result follows the structure of the query:

Now, let us focus on altering the database through a mutation. In GraphQL, this is the way a client runs “stored procedures” on the Server side. The Star Wars example has tooling for factions in the Star Wars universe, but there are currently no factions defined. Let us amend that by introducing the rebels:

This query uses the GraphQL feature of input variables. In the UI, you can click and expand the section Query Variables under the query pane. This allows us to build a generic query like the one above and then repurpose it for creating any faction by providing the input variables for the query:

The server, when you execute this query, will respond with the creation of a new Faction and return its id, name and starships:

We can now query this faction by its Id because it was added to the system:

The system also persisted the newly created faction in its database so restarting the system keeps the added faction.

With the rebels in the Graph, we can now create a new Starship, a B-Wing, which we will add to the graph. We will also attach it to the newly formed faction of Rebels. The mutation here exemplifies operations in which you bind data together in GraphQL. Our mutation looks like:

We create a new Starship, a B-wing, in the Rebels faction. Note the resulting object, IntroduceStarshipPayload, contains the newly created Starship as well as the Faction which was input as part of the query. This is common in GraphQL: return every object of interest as part of a mutation.

The result of the query is:

Note how the newly formed starship is now part of the Rebel factions starships, and that the total count of starships in the Faction is now 1. The created field on the Starship is automatically generated by the system as part of introducing it.

Note: Not all the fields on the newly formed starship are "valid" insofar we decided to reduce the interface here in order to make it easier to understand in the tutorial. A more complete solution would force us to input every field on the Starship we just introduced and also use sensible defaults if not given.

This tutorial will tell you how to create your own system which can satisfy queries as complex and complicated as the examples we just provided. It will explain the different parts of the GraphQL system and how you achieve the above.

This tutorial doesn’t cover everything in the repository:

The purpose of a GraphQL server is to provide a contract between a client and a server. The contract ensures that the exchange of information follows a specific structure, and that queries and responses are in accordance with the contract specification.

Additionally, the GraphQL servers contract defines what kind of queries are possible and what responses will look like. Every query and response is typed and a type checker ensures correctness of data.

Finally, the contract is introspectable by the clients. This allows automatic deduction of queries and built-in documentation of the system interface.

Thus, a GraphQL server is also a contract checker. The GraphQL system ensures that invalid queries are rejected, which makes it easier to implement the server side: you can assume queries are valid to a far greater extent than is typical in other systems such as typical REST interfaces.

In order to get going, we need a world in which to operate. First, we must provide two schemas: one for the GraphQL system, and one for the Mnesia database.

The GraphQL schema defines the client/server contract. It consists of several GraphQL entity kinds. For example:

A somewhat peculiar choice by the GraphQL authors is that the world of Input and Output objects differ. In general, a Client has no way to "PUT" an input object back into the Graph as is the case in REST systems. From a type-level perspective, client requests and server responses have different polarity.

It may seem as if this is an irritating choice. You often have to specify the “same” object twice: once for input and once for output. However, as your GraphQL systems grows in size, it turns out this choice is the right one. You quickly run into situations where a client supplies a desired specific change where many of the fields on the output object doesn’t make sense. By splitting the input and output world, it is easy to facilitate since the input objects can omit many fields that doesn’t make sense.

In a way, your GraphQL system is built such that changes to the data is done by executing “transactions” through a set of stored procedures. This can be seen as using the "`PATCH`" method of RESTful interfaces and not having a definition of PUT.

GraphQL splits the schema into two worlds: query and mutation. The difference from the server side is mostly non-existent: the GraphQL system is allowed to parallelize queries but not mutations. But from the perspective of the client, the starting points in the graph is either the query or the mutation object.

GraphQL implements what is essentially CQRS by making a distinction between the notion of a query and a mutation. Likewise, the server side makes this distinction. But on the server side it is merely implemented by having different starting objects in the graph execution.

Our Star Wars schema uses the database Mnesia as a backend. It is important to stress that you often have a situation where your database backend doesn’t map 1-1 onto your specified GraphQL schema. In larger systems, this is particularly important: the GraphQL schema is often served by multiple different backends, and those backends are not going to cleanly map onto the world we expose to the clients. So the GraphQL schema contract becomes a way to mediate between the different data stores. As an example, you may satisfy some parts of the GraphQL query from a dedicated search system—​such as ElasticSearch—​while others are served as rows from a traditional database, such as MySQL or Postgresql. You may even have a message queue broker or some other subsystem in which you have relevant data you want to query. Or perhaps, some queries are handled by micro-services in your architecture.

Over the course of having built larger systems, we’ve experienced that mappings which tries to get isomorphism between the backend and the schema creates more problems than they solve. Small changes have consequence in all of the stack. Worse, you can’t evolve part of the system without evolving other parts which impairs the flexibility of the system.

Another problem is that you may end up with an impedance mismatch between the Objects and links of the GraphQL query and the way you store your data in the backend. If you force a 1-1 relationship between the two, you can get into trouble because your GraphQL schema can’t naturally describe data.

A common problem people run into with Mnesia is how to “get started”. What people often resort to are solutions where an initial database is created if it doesn’t exist. These solutions are often brittle.

Here, we pick another solution. A helper can create a database schema for us, with all the necessary tables. The real release assumes the presence of an initial database and won’t boot without one. This means the Erlang release is simpler. There is always some database from which it can boot and operate. That database might be the empty database since we are just starting out. But in particular, the release won’t concern itself with creating an initial database. Rather it will assume one is already existing.

The situation is not much different than using a traditional schema-oriented database. Usually, you have to create the database first, and then populate the schema with some initial data. It is just because of Rails/Django like systems in which databases are migrate-established, we’ve started using different models.

To get up and running, we begin by constructing a Mnesia schema we can start from. We do this by starting a shell on the Erlang node and then asking it to create the schema:

The call create_schema() runs the following schema creation code:

Creating the schema amounts to running a set of commands from the Mnesia documentation. The helper function to create tables contains a large number of tables, so we are just going to show two here:

In Mnesia, tables are Erlang records. The #planet{} record needs definition and is in the header file sw_core_db.hrl. We simply list the entries which are defined the SWAPI GraphQL schema so we can store the concept of a planet in the system:

Every other table in the system is handled in the same manner, but are not given here for brevity. They follow the same style as the example above.

Once we have introduced tables into the system, we can turn our attention to populating the database tables. For this, we use the SWAPI data set as the primary data source. This set has its fixtures stored as JSON document. So we use jsx to decode those JSON documents and turn them into Mnesia records, which we then insert into the database.

We can fairly easily write a transformer function which take the JSON terms and turn them into appropriate Mnesia records. Planets live in a fixture file planets.json, which we can read and transform. Some conversion is necessary on the way since the internal representation differ slightly from the representation in the fixture:

Once we have this function down, we can utilize it to get a list of Mnesia records, which we can then insert into the database through a transaction:

The code to read in and populate the database is fairly straightforward. It is the last piece of the puzzle to inject relevant data into the Mnesia database:

This creates a fixture in the database such that when we boot the database, the planets, transports, people, …​, will be present in the Mnesia database when we boot the system.

Once we have run the schema creation routine, a file called FALLBACK.BUP is created. We copy this to the database base core in the repository

which makes the empty schema available for the release manager of the Erlang system. When we cook a release, we will make sure to copy this initial schema into the correct Mnesia-directory of the release. Because the file is named FALLBACK.BUP, it is a fallback backup file. This will “unpack” itself to become a new empty database as if you had rolled in a backup on the first boot of the system. Thus we avoid our system having to deal with this problem at start up.

We now have the ability to create new database tables easily and we have a Mnesia database for backing our data. This means we can start turning our attention to the GraphQL schema.

In GraphQL, you have a special type, ID, which is used to attach an identity to objects. It is typically used as a globally unique identifier for each object in the graph. Even across different object types; no two objects share a ID, even if they are of different type.

The ID is always generated by the server. Hence, a client must only treat an ID as an opaque string value and never parse on the string value. It can only return the ID value back to the server later on.

To make this more obvious, GraphQL implementations usually base64 encode their ID-values. In Mnesia, our rows IDs will be integers, and they will overlap between different types/tables in the database. Since IDs should be globally unique, we use an encoding in GraphQL. The Starship with id 3 will be encoded as base64("Starship:3"). And the planet Tatooine taken from the System Tour is encoded as base64("Planet:1"). This definition somewhat hides the implementation and also allows the server backend to redefine IDs later for objects. Another use of the encoding is that it can define what datasource a given came from, so you can figure out where to find that object. It is highly useful in migration scenarios.

The encoder is simple because we can assume the server provides valid values:

The decoder is a bit more involved. It requires you to fail on invalid inputs. We usually don’t need to know what was invalid. We can simply fail aggressively if things turns out bad. A debugging session will usually uncover the details anyway as we dig into a failure.

The Relay Modern specification (see Relay Modern) contains a standard for an Object Identification interface. Our schema implements this standard in order to make integration simpler for clients supporting the standard. The interface, also called the Node interface because of its type, allows you to “start from” any node in the graph which has an id field. That is, every node with identity can be a starting point for a query.

The interface is most often used as a way to refresh objects in a client cache. If the client has a stale object in the cache, and the object has identity, then you can refresh a subset of the graph, setting out from that object.

The interface specification follows the standard closely:

The Erlang version of GraphQL allows a certain extension by the Apollo Community @ Github, who are building tools GraphQL in general. This extension allows you to use Annotations in GraphQL schemas to attach more information to particular objects of interest. We use this for documentation. You can annotate almost anything with +description(text: "documentation") which in turn attaches that documentation to an entity in the Graph.

Multi-line comments are also possible by using a backtick (`) rather than a quote symbol ("). These allows larger Markdown entries to be placed in the documentation, which tends to be good for documentation of APIs.

We follow the specification for describing object types. Thus, if you describe an object like a starship as type Starship { …​ } the system knows how to parse and internalize such a description. In the following, we don’t cover all of the schema, but focus on a single type in order to describe what is going on.

The type system of GraphQL is “moded” as in Prolog/Twelf/Mercury or is “polarized” in the sense of type systems and semantics. Some data has “positive” mode/polarity and flows from the client to the server. Some data has “negative” mode/polarity and flows from the server to the client. Finally, some data are unmoded and can flow in either direction.

GraphQL distinguishes between input and output types. An input is positive and an output is negative. While at first, this might seem like a redundant and bad idea, our experience is that it helps a lot once your system starts to grow.

In GraphQL, the way you should think about Mutations are that they are “stored procedures” in the backend you can execute. You don’t in general get access to a command which says “PUT this object back”. Rather, you get access to a mutation which alters the object in some predetermined way: favoriteStarship(starshipId: ID!) for instance.

Because of this, GraphQL is built to discriminate between what types of data the client can send and what types of data the server can respond with.

Input and output objects are subject to different rules. In particular, there is no way to input a null value in an input. The way a client inputs a no value input is by omission of the input parameter in question. This choice simplifies clients and servers.

There are times where the client wants to input a number of values at the same time. You could add more parameters to the field:

but this often gets unwieldy in the longer run. Rather than this, you can also solve the problem by creating an input object which only works in the input direction:

In turn, the client can now input all these values as one. Grouping of like parameters are quite common in GraphQL schemas. Note how input object fields are often vastly different from the output object it corresponds to. This is the reason why having two worlds—​input & output—​is useful.

It is possible to define default parameters in the schema as well, as seen in the above example. This is highly useful as a way to simplify the backend of the system. By providing sensible defaults, you can often avoid a specialized code path which accounts for an unknown value. It also simplifies the client as it doesn’t have to input all values unless it wants to make changes from the defaults. Finally it documents, to the client, what the defaults are.

In GraphQL, an interface is a way to handle the heterogeneous nature of modern data. Several objects may share the same fields with the same types. In this case, we can provide an interface for those fields they have in common.

Likewise, if we have two objects which can logically be the output of a given field, we can use a union to signify that a set of disparate objects can be returned.

In the case of an interface, the client is only allowed to access the fields in the interface, unless it fragment-expands in order to be more specific. For unions, the client must fragment expand to get the data.

The Star Wars Schema has an obvious example of an interface via the Node specification above, but there is another interface possible in the specification: both Starship and Vehicle shares a large set of data in the concept of a Transport. We can arrange for this overlap by declaring an interface for transports:

And then we include the interface when we declare either a starship or a vehicle. Here we use the Starship as an example:

Interfaces and Unions are so-called abstract types in the GraphQL specification. They never occur in concrete data, but is a type-level relationship only. Thus, when handling an interface or a union, you just return concrete objects. In the section Type Resolution we will see how the server will handle abstract types.

In the schema, it is possible to enter default values: field : Type = Default. We already saw an example of this in the section on inputs for introducing starships.

Defaults can be supplied on input types in general. So input objects and field arguments can take default values. When a client is omitting a field or a parameter, it is substituted according to GraphQL rules for its input default.

This is highly useful because you can often avoid code paths which fork in your code. Omission of an array of strings, say, can be substituted with the default [] which is better than null in Erlang code in many cases. Default counters can be initialized to some zero-value and so on. Furthermore, in the schema a default will be documented explicitly. So a client knows what the default value is and what is expected. We advise programmers to utilize schema defaults whenever possible to make the system easier to work with on the client and server side.

Schema defaults must be type-valid for the type they have. You can’t default a string value in for an integer type for instance. Also, the rule is that non-null yields to default values. If a default value is given, it is as if that variable is always given (See the GraphQL specification on coercion of variable values).

The root setup defines how a query begins by defining what type in the schema specification is the root for queries and mutations respectively. By convention, these types are always called Query and Mutation so it is easy to find the Root’s entry points in the Graph.

The query root must be injected into the schema so the GraphQL system knows where to start. This is done in the file sw_core_app in the function setup_root:

The mapping rules of the GraphQL system defines how the types in the schema maps onto erlang modules. Since many mapping can be coalesced into one, there is the possibility of defining a default mapping which just maps every unmapped object to the default.

All of the mappings goes from an atom, which is the type in the Schema you want to map. To an atom, which is the Erlang module handling that particular schema type.

Consider the following GraphQL query:

which returns the following response:

The id given here can be decoded to "Species:15". We can use the Erlang shell to read in that species:

When the field created is requested, the system will return it as {{2014,12,20},{9,48,2}} and because it has type DateTime it will undergo output coercion to the ISO8601 representation.

How the field is requested and fetched out of the Mnesia database is described in the section Object Resolution.

You define enum values in the schema as mandated by the GraphQL specification. In the Star Wars schema, we define the different film episodes like so

which defines a new enum type Episode with the possible values PHANTOM, CLONES, …​.

In order to handle these enum values internally inside a server, we need a way to translate these enum values. This is done by a coercer module, just like [scalar-representation]. First, we introduce a mapping rule

In the schema mapping (see Mapping rules for the full explanation). This means that the type Episode is handled by the coercer module sw_core_enum.

The module follows the same structure as in Scalar Resolution. You define two functions, input/2 and output/2 which handle the translation from external to internal representation and vice versa.

In the example we turn binary data from the outside into appropriate atoms on the inside. This is useful in the case of our Star Wars system because the Mnesia database is able to handle atoms directly. This code also protects our system against creating illegal atoms: partially because the coercer module cannot generate them, but also because the GraphQL type checker rejects values which are not valid enums in the schema.

In the output direction, our values are already the right ones, so we can just turn them into binaries.

In GraphQL, we can run a query which asks for a film by its episode enum and then obtain some information on the film in question:

Note how we use the value JEDI as an enum value for the episode in question. The GraphQL type checker, or your GraphiQL system will report errors if you misuse the enum value in this case.

The output is as one expects from GraphQL:

Here, the field episode returns the string "JEDI" because the JSON output has no way of representing an enum value. This is the GraphQL default convention in this case. Likewise, enum input as a query parameter, e.g. as part of query Q($episode : Episode) { …​ }, should set the $episode value to be a string:

Which will be interpreted by the Erlang GraphQL as an enumerated value.

We start with plain field access on the Planet and Starship types. Our mapping rules have mapped 'Starship' ⇒ sw_core_starship so the field handling lives in the module sw_core_starship. Likewise, we map 'Planet' ⇒ sw_core_planet and so on. In general, object resolution is handled by a single function, execute/4:

The function is called execute because it relates to the GraphQL notion of executing a query on the server side. And because the word “execution” maps precisely onto what you are doing. You are invoking functions on the server side, relating to the query by the client.

In the following we give a detailed explanation of each of the fields here and what their purpose are:

The Context is a map which contains contextual information about the query. Its primary purpose is that the developers can set data into the context at the top-level when they start processing a GraphQL query. In turn, the context is often stuffed with data from the outside of the GraphQL system:

Additionally, the context also contains some base information added by the GraphQL system. Most notably the current object type and field. This allows one to build some extremely generic execute/4 functions that handles large classes of objects.

The Obj field points to the current object we are rendering for, e.g. a Starship given as the a value #starship{…​}. This field is the binding of a type to a concrete object we are working on. As an example, a B-wing is a Starship, an X-wing is a Starship, and a TIE-fighter is a Starship. So when the execute/4 code runs, it needs to know what concrete loaded object is in play. Another way of seeing it is that the Obj is the object the Cursor is currently pointing at in the Graph Rendering.

The field is the current field which the client requested in the object. The field is also inside the context, but because it is very common it is also an argument to the function directly. The field allows you to pattern match on different fields of the query.

The arguments are always of type #{ binary() ⇒ term() }; mapping from field name to field value. If a client queries

then we will have Args = #{ \<<"id">> ⇒ \<<"SOMEID">>} and we can proceed by pattern matching on this object.

An important thing to cover at this point is how mappings of input arguments are done in GraphQL. A GraphQL client has no way of inputting a null value. It is not allowed for the client to ever use a null in any input position. Rather, the way a client specifies it has no value, is by omission of a given input field.

The GraphQL system considers the omission of a field depending on the configuration of that field:

In short, an object resolution module can assume that all fields are always present in the Args map, either populated by a default value or by a null value if that field has no default. It is a brilliant design choice by the GraphQL specification designers: clients have one unambiguous way to input “no value” and servers have one unambiguous way of processing “no value”.

In our system, we have a module sw_core_planet which handles the execution parts of planets. Planets are rather simple objects in that most of their internals are directly mapped to an underlying Mnesia database. The execute/4 function describes how the Mnesia records are mapped into the GraphQL world of fields the client requested.

The only exported function is execute/4 which we dissect a bit here. We omit some parts which are not very interesting as of now:

In our case, since we are working with Mnesia data, we need a projection function to take fields out of the record and return them to the GraphQL system. Note that we can use this to rename fields. The GraphQL specifies rotationPeriod whereas we use the Erlang idiomatic internal name rotation_period.

If you think this is a lot of typing, you can choose to represent Planets as a map() and then the execution function is basically

but the price you pay for doing so is that the names in the Obj has to match the names in the GraphQL specification. In our experience, it is often the case that things evolve and you need to rename fields. So this is not always a desirable solution.

When a Starhip is loaded from the database, remember from Interfaces & Unions that we are loading a starship as two rows: One for the transport part, which is shared with vehicles, and one for the starship part which is unique to starships. This means that the “current object” when field resolving on a starship is a pair of a transport and a starship row. The resolver function must handle this, by retrieving the field from either the transport or the starship. This is easily done in the execute/4 function:

The example here exemplifies that a current object can be any Erlang term you like. The output from the GraphQL system is always being mediated by an execute/4 function, so as long as you can translate from that Erlang term and into a valid field value, you are golden.

Our Planet execute function handles the case where we have a loaded planet and want to output its contents. But it doesn’t say anything about how to fetch a planet from the database. This section handles the loading of data from Mnesia while running GraphQL queries.

The type Query in the GraphQL specification (see Queries & Mutations) contains a field node and a field planet which are used to load any node or a planet respectively. The loader is the same, and planet is just a specialization of the node loader.

Let us define the execution function for handling loading. We simply extract the interesting data and forward our query to a plain Erlang function:

The function which actually loads the object can now be written:

To load a particular node, we first attempt to decode the ID into its type and its Mnesia ID. Once we know its decoded form, we have a helper routine which carries out the actual load. The loader asks the database to load data, and also verifies the allowed types if needed.

The specification of a Planet contains a field residentConnection which links the planet to the residents on the planet. To handle such a link in the code, we begin by implementing the code that tells GraphQL how to render a Person. It follows the same structure as a Planet from above, and there is little new stuff in those parts.

In the object resolution for the Planet we must perform a query in Mnesia to obtain the relevant persons and then build up the correct pagination structure.

We set up a Mnesia transaction through QLC, and then we look for the people whose homeworld matches our desired Planet ID. Once we have loaded all such people, we pass them to the pagination system which slices the data according to the clients specification.

The pagination here follows the Relay Modern specification for pagination and is described in the section Pagination.

The module sw_core_object contains a default mapping which is the execute/4 function used for any object that isn’t overridden by a more specific mapping rule. The implementation is sinisterly simple:

The default mapper assumes it is given a map() type and then it looks inside that map for fields. This is convenient because you will have lots of output types which are plain and simple. You don’t want to invent a specific record for such an object, nor do you want the tedium of writing an execute/4 function for all of them.

As an example the residentConnection field we just handled in Walking in the Graph returns an object of type ResidentsConnection. The pagination engine returns a map() which happens to contain precisely the fields of a ResidentsConnection. The default mapper then takes care of everything else if the user requests fields inside the ResidentsConnection.

A particularly common case is when a type is an array [T] of a certain type T. To resolve an array type in GraphQL, you must return a value in which every object in the list is wrapped in an option tuple: {ok, Val} | {error, Reason}.

Suppose, for instance, we have retrieved three values A, B, and C and the retrieval of the B value failed. In this case you would return

to signify that the two values A and C suceeded but B failed. If the data fetch fails as a whole you can of course fail the full field by returning {error, Reason}.

In the Star Wars schema, we have a type Species for each possible species in the star wars world. Every Person belong to a Species. Since species have a set of possible eye-colors, we have a type eyeColors : [String] in the specification. The execute/4 function uses the above rules to generate a list of eye colors:

Since the result can’t fail, we wrap every result in an {ok, EC} to state that every eye colors loaded succesfully.

Object resolution of mutations works the same way as object resolution for every other kind of type in the graph. When the Mutation object is request in a mutation, the field resovler will run and call an execute/4 function for the mutation. In our example, our mutation code looks like:

We write a generic mutation path. First we unwrap the input argument and then dispatch to a function which handles the clientMutationId entries inside the input. It then calls the actual mutation code in execute_mutation and builds up an appropriate result containing clientMutationId inside the payload.

The reason we do this is due to Relay Modern and its conventions for mutations (see Inputs & Payloads). Because every mutation contains a mutation id, we can just handle all of them in one go and then dispatch later on. While here, we also make the input data cleaner so it is easier for the execute_mutation call to work.

The execution function simply forwards to the target module and then packs the result in a map so it satisfies the …​Payload objects. the idea being that we are then returning something of the correct type according to the conventions:

The choice of dispatching to modules such as sw_core_faction and sw_core_starship is entirely a convention which served us well. For some GraphQL servers it is better to pick another module for this. As an example, at ShopGun we dispatch to a general business logic layer for mutations rather than handling in the same module as the query layer. Due to CQRS, it was easier to build the system in this fashion.

We now turn our attention to the notion of executing a query. It is instructional because it explains how a query is executed in the GraphQL system while using the parts we have defined up until now.

Suppose we look at a query such as the following

and look at how the system will execute such a query.

First, a cursor will be set in the root of the currently selected Query object in the Graph. Since this is mapped by the schema into the module sw_core_query, we start by visiting that module and execute fields there. The cursor will point to an initial object of the query, which is set by the developer. We will ignore this object in our implementation.

Next, since the field node is requested, we execute the call

which will execute sw_core_db:load/2 on the Starship we requested. The value returned is the value {ok, #planet{} = Planet} for the planet we requested.

Now, because the type of the node field is Node, the system will know that it has loaded something of interface type. Such a type is abstract and must be made concrete. Thus we use Type Resolution and a call

is performed. This call will return {ok, 'Planet'} as the value. So the system knows that it can proceed by assuming the Node was really a Planet.

The cursor now moves to the planet value and this becomes the new object of the query. Field resolution and fragment expansion for the planet object now begins. Calls to sw_core_planet:execute/4 are made 3 times for the fields id, name and climate. Our projection functions return values inside the planet, and this becomes part of the GraphQL response to the client.

To recap: the GraphQL system drives the query and makes callbacks at appropriate times to your resolver function in order to satisfy the query. You only have to implement the callbacks. The looping itself is handled by GraphQL.

To make GraphQL work with Cowboy, we use the application sw_web. This application then uses sw_core in order to run the system. One could imagine adding other applications to the system if you need more transports. The web application needs a dispatcher in order to run:

We could have picked any place to run the GraphQL interface, but this code uses / at the root.

The Cowboy setup is straightforward, except that we manipulate a couple of variables in order to make cowboy play better with GraphiQL. Look at the file sw_web_app.erl for the details.

We set up the cowboy handler as a REST handler, because it is easy to do, and because it automates a large set of things we’d like to do. Our plan is to use content-negotiation: a web server will be served a UI for GraphQL by default, but if the a client request comes in, we will pass that to the GraphQL system.

The cowboy_rest model stems from an idea pioneered by Webmachine. We can depict an HTTP request as a flow chart where each decision point is a node in the chart. Since every request follows this flow chart, it makes sense to use a classic Erlang model: code the generic/general parts inside a main module cowboy_rest, and then provide it with a callback module. Whenever a decision node is reached, the callback will be executed and the decision will follow the choice made by the callback. If no callback function is present, we use a default resolution.

Relay Modern defines an object identification specification together with an interface Node used to retrieve objects which are cached on the client side. The specification https://facebook.github.io/relay/graphql/objectidentification.htm defines the details of this.

This tutorial already implements the Node interface. The section Identity encoding talks about the creation of globally unique identifiers, and the section on Queries & Mutations describes the concept of a Node. Finally, the section DB Loading describes how nodes are loaded, generically, from the database backend.

Taken together, this implements the object identification specification.^[6]

TBD

The Relay Modern pagination specification (https://facebook.github.io/relay/graphql/connections.htm) defines how pagination connections and cursors are supposed to work. We have a simple implementation of these ideas in Erlang in this tutorial.

Real world systems will benefit from having a close linkage between a given data source and the pagination system. You can gain lots of efficiency if you request data after you know what window the client desired. The implementation is faithful to the specification and can be used as a start.

Furthermore, different data sources tend to provide different ways to paginate. An RDBMS can use the OFFSET/LIMIT pairs, or a time-interval column. [Oracle and MS SQL Server use different notions, but can achieve the same thing] Some systems provide cursors which can be sent with a follow-up query. And so on.

In the Relay Modern specification, the cursor is a server side controlled piece of data. A client is not allowed to manipulate it. This allows the server to use the same pagination scheme for many different types of data stores. And this provides a large amount of flexibility.

The pagination function is called as select(Elements, Args) where Elements is the set of edges we are paginating for, and Args is a map containing the fields first, last, after, and before. We expect the elements to be the full results of every eligible elements. This is possibly large and should be optimized in a real implementation. The body of the function looks like the following and follows the specification very closely:

This function cuts off a window with respect to either the before or the after cursor. We can handle this through pattern matching in Erlang:

The function is pretty straightforward, since the cursor contains the position at which to cut. So we can simply split the element list at the right point and return it.

This function evaluates the first and last parameters and only returns the first/last K elements of the cut-off window. It follows a simple scheme:

To build up the PageInfo object, we use the following small helpers function which will determine if there is more elements after the window in either direction. They closely follow the specification:

A cursor in this setup is the base64 encoding of the position:

GraphQL is a query language. If a client is able to run any query in the world, you may get into trouble with overload. Your system has to parse, type check & validate each request. And if the request is expensive, it puts unnecessary toll on your backend systems. To avoid this, production implementations support the ability to prepare a query document containing all the queries a client wants to make. Once and for all the document is parsed, type checked, and validated. Then a reference is given back to the client. Clients who wish to run a query can then supply this reference and an opName inside the query document to run that query.

This is much faster since the Server only has to execute the query and can avoid going through the validation steps again and again. While the Erlang GraphQL system is fast, about 4/5 of a query is pre-processing time before execution. In other words, you can speed up the GraphQL by quite a margin if you use stored procedures.

In addition, you can also arrange that a client isn’t able to construct new query documents without authorization. This means developers can deploy new query documents when they deploy new versions of an application, but a user of said application cannot produce new queries dynamically.

In short:

It is also possible to build hybrid systems. Let dynamic queries be limited in the backend to a few at a time. Thus, dynamic queries are far less likely to “take out” your system.

If you give developers access through an API key, you can demand that they build query document should they want to run more than, say, 600 queries per hour against your system. This is 10 queries per minute, which is usually fine for development—​Once the system is done, you provide a query document for preparation, and then the prepared document is used.

Another advantage of prepared documents is that the server side controls what gets executed. This allows you to target a problematic query at the server side and patch it, for instance by lowering the size of a pagination window, or making the query simpler by not providing certain parts. On the other hand, many of those problems should be fixed by altering the server to become more robust.

TBD

TBD

A rather useful representation of objects is to have some additional metadata on your object for use by the GraphQL system in addition to the base data fields which the client can request.

If your object representation is a map(), you can add special fields into the map which is used by the GraphQL system. You can add those fields as you load the object from the backend database, in order to make it easier to work with later. In Erlang systems, due to immutability, a pointer to some static data is essentially free, as long as terms share the same base value. So don’t be afraid to add some metadata on your object.

A common convention is to use a special atom such as '$tag'.^[7] You can then add data under that key in the map which is useful to the GraphQL backend only.

In addition, our convention is that fields which must be derived begin with an underscore (e.g., _images). This makes it clear to the reader that the data is not isosmurfically mappable into the Graph but requires some kind of transformation.

Rather than represent an object as a record such as #starship{} you represent the data as a wrapped term: {#starship{} = Ship, MetaData} and then you write your execution function such that it operates on the wrapped term rather than the raw Ship. This has the advantage of keeping the data separate from the raw plain data object. The sacrifice, though, is you have to do more work in your object resolution code.

A common want when designing API systems is to avoid the need for continual translation of backend data to the GraphQL schema. A common solution to this problem is to make the database schema 1-1 with the GraphQL schema, often called an isomorphic representation.^[8] However, our experience is that such a 1-1 mapping is detrimental to the development of the system. It is common the GraphQL schema and the underlying data evolve at different paces and that new data sources are added as you go along.

Thus, a piece of advice is to know when to break from the 1-1 mapping and build your own translation layer in order to handle the gradual evolution of the database schema and the GraphQL contract. In general, you shouldn’t be afraid of breaking the isomorphic representation if that turns out to help you define your system in a better way. On the flip side, inventing new terminology and names shouldn’t in general be done for the sake of doing so. The advantage of having an isomorphism between the contract and the database is that you don’t have to explain to people what the mapping means.

In many larger HTTP systems, it is common to have a “middleware stack”. In a middleware stack, there is a section of code which is run for every request to the system. It is often used for a number of different cases:

In a GraphQL, these concerns tend to split into two groups:

In Erlang GraphQL we decided to create a system in which middleware handling is put into the hands of the programmer outside of the GraphQL system. There is no way to “inject” middlewares in the system. Rather we handle the stack by providing functionality which allows the programmer to write their own equivalent.

The reason is we recognize how these stacks tend to be application specific and also tend to be changing a lot. So by keeping them outside the Erlang GraphQL itself we avoid having to cater for them all the time.

TBD

TBD

If you have data where computation is circular, you will have to make sure you don’t build an infinite loop in the data. This system has support for lazy evaluation, but you will have to write it yourself and handle it in your side. GraphQL provides the facilities, but not the solution here.

When you return an object to GraphQL, you can return any data. Further recursion into the query will then call execution functions on the underlying data. If you return an object such as

you delay the computation of Expr because it is wrapped in a function. Now, when you actually hit the field, in another execute function, you can handle the lazy node by evaluating it when the field is hit:

This ensures you only force/unroll the computation if the field is actually invoked, and you obtain lazy evaluation over the Graph.

The method is useful in the case where your data is naturally cyclic, but where any query has a limited depth. By delaying computation, you will only force the computation the necessary amount of times, rather than eagerly entering an infinite loop.

Another common use case is when some parts of your computation is known when you build the initial object, but the computation of the content is expensive. By delaying the computation itself inside a thunk, you only compute that part if it turns out to be necessary.

In GraphQL, fields are nullable by default. A generic field f : T can either take on the value of T or the value null if the rendering of the field fails for some reason.

In contrast, a field can be non-nullable, f : T! in which case the field is not allowed to take on the value of null.

If you try to complete a non-null field in an object, and null is returned, or an error occur, then the whole object becomes null. This notion propagates until all of the query becomes null or we reach a nullable field, whichever comes first.

Hypertext embedded in responses can have users “click around” in your API. If you embed the possible operations as links in responses, a client can use returned data to learn what it can do with the data. Roy T. Fielding’s PhD thesis covers this in great detail.

GraphQL doesn’t implement HATEOAS, but it gets fairly close to the idea. Given that a GraphQL query can be introspected, you can gradually learn about the interface as a client and utilize that interface. In practice however, it is common to lock down the possible queries for a given client, in order to protect the system and get security.

The context map contains a number of base fields before the developers extends the context with their own fields. This section describes those fields and their purpose:

CQRS stands for Command-Query Responsibility Separation. The idea stems from the observation that querying data often have a different feel than commanding the system to do changes. So rather than trying to solve both in one interface, you slice the system such that you have a query-part which pertains only to querying data, and a command-part which pertains to mutating data.

Often, the command section becomes a system based on an append-only event log in which command processors read events and make changes to the system. These changes are then made persistent and ready for query.

The Query system is built with dynamic arbitrary queries in mind and is focused on this only.

The splitting often helps larger system as they tend to have large differences in the Query part and the Command part.

We often use the term “cursor” in this tutorial. Imagine that a GraphQL is rendered by moving a cursor around in the data set and then rendering each part of the query as the cursor moves around. As the cursor traverses (recursively) deeper into the data set, more parts of the query may be rendered on demand.

In practice, the cursor can be executed in parallel. If you submit a query you must assume that rendering will happen in parallel when possible. In contrast, a mutation will always process the query serially one element at a time. This is to make sure changes for a given query are not interfering with each other.

The rebar3 configuration file. It contains information about the immediate system dependencies of the project. It also contains information for relx the release builder rebar3 uses. This is used to assemble a release by copying the Erlang runtime as well as the necessary support libraries into a release directory. This directory can then be archived via tar(1) or zip(1) and shipped for a production release.

Contains some convenience targets when building the software. In practice you have some support-calls that has to be made outside the build tool in many cases. This Makefile contains recipes for doing that, so you don’t forget what is to be done.

Instructions for the reader on GitHub. Also instructions on how to build the documentation and where to go next.

Dependency locking for reproducible builds. It makes sure you get versions of packages which are known to be working together and that upgrades of software is a deliberate action rather than an implicit one.

Release VM arguments. The release handler makes sure these become part of the system release so you can set parameters on the command line of the Erlang runtime. It is often used to fine-tune schedulers, memory allocation, or the upper bound on processes or ports.

The configuration file of the release. This allows us to override application-specific configuration knobs in the final release. Often, configuration can be handled by adding a call to application:get_env/3 in the source code and then adding a default value to an applications .app file. Then it can be overridden in the sys.config file later, if a release needs a different setting. Another common use is to provide varying configuration for different environments.

The applications provided by this repository. See the following sections for their description.

The schema definition file which can be read by the Erlang GraphQL system. It defines the schema rules for the Star Wars API.

Application description file which rebar3 compiles into ebin/sw_core.app. It contains a number of important sections for the project:

The application behavior used to start the sw_core application. This file also contains the schema-loading code: when the system boots, we attempt to load and validate the schema. Any mistake will abort the boot process and print out a failure.

This header file contains the records we are using in our Mnesia database. One could have spread these over multiple files, but since the system is fairly small we use a single file for this. It is likely a larger system would split this into smaller sections.

Wrapper around the database calls which are common in the system. Also contains the functions for creating the initial schema, which can be invoked without the sw_core application running.

Handling of ID values in the Graph from the client. Provides encoding and decoding of identifier values so we know what object they refer to internally.

Input and output coercion for scalar values

Describes how this GraphQL instance converts from abstract types such as Interfaces and Unions to concrete types. For instance how the system converts from the Transport interface to a Starship or Vehicle.

Top level supervisor referring to long-lived processes in this application.

Code for resolving objects of type Film.

Code for resolving generic objects not covered more modules which specialize to a particular object type. Generic objects are represented as maps in the system and this module handles maps in general. This allows us to easily construct new types in the Graph without having to write special handlers for each.

This file implements generic pagination code for the API. It is an implementation of Relay Modern’s conventions for paginations and cursors (see Pagination).

Code for resolving objects of type Person.

Code for resolving objects of type Planet.

Code for resolving objects of type Query. The query object is main entry-point into the graph for data queries in which data is read out of the API. Notably it contains code for loading arbitrary objects if the client obtained a handle (id) on the object earlier.

Code for resolving objects of type Species.

Code for resolving objects of type Starship.

Code for resolving objects of type Vehicle.

This application implements the web UI and the HTTP transport on top of the Core application.

Application callback for the sw_web application. Also initializes the cowboy web server with its dispatch rules and the configuration of cowboy.

The main handler for GraphQL requests in the system. It provides transport between GraphQL and HTTP.

Main supervisor. Currently it has no children, but exists as a way to appease the application controller by giving the application a specific pid() it can use to know if the application is up and running.

Wrapper around responses. It makes sure that an Erlang term is representable in JSON by converting something like a tuple into a binary value. This allows a JSON encoder to handle the Erlang term without problems.

Another reason for doing this is that we eliminate a lot of 500 Status code responses from the system.